Specify authentication parameters

Alfabet 's generic API integration interface supports HTTP, API Key, OAuth and OAuth2 authentication.

• HTTP Authentication

  Set the following parameters in the Authentication XML element:

  • <Authentication
    • Name="HTTPAuthenticationForMyApp"
    • Type="Http"
    • UserName="User1"
    • Password="User1Password!"
  • >
  • </Authentication>

  XML element/ XML attribute	Value	Mandatory
  Authentication
  Name	The name of the authentication definition. The name is used to identify the authentication definition in other parts of the XML specification.	yes
  Type	Http	yes
  UserName	A valid user name to access the RESTful service of the third-party component.	yes
  Password	The password of the specified user to access the RESTful service of the third-party component. For security reaons you should specify at least the user password as a link to a server variable instead of using plain text . The server variable is either stored encrypted in the server alias of the Alfabet Server.	yes

• Authentication with API Key

  Set the following parameters in the Authentication XML element:

  • <Authentication
    • Name="KeyAuthenticationForMyApp"
    • Type="APIKey"
  • >
    • <APIKey Key="KeyField" Value="KeyValue">
  • </Authentication>

  XML element/ XML attribute	Value	Mandatory
  Authentication
  Name	The name of the authentication definition. The name is used to identify the authentication definition in other parts of the XML specification.	yes
  Type	APIKey	yes
  APIKey
  Key	The RESTful service header field name for the key.	yes
  Value	the API key for access to the RESTful service. For security reaons you should specify at least the API key as a link to a server variable instead of using plain text. The server variable is stored encrypted in the server alias of the Alfabet Server.	yes

• OAuth Authentication

  The authentication tokens of the third-party component must match the standard authentication definitions. You can view the standard at https://www.oauth.com.

  OAuth authentication is a dynamic authentication mode with a separate token request for each session.

  Set the following parameters in the Authentication XML element:

  • <Authentication
    • Name="OAuthAuthenticationForMyApp"
    • Type="OAuth"
    • Flow="Custom"
    • Mode="Dynamic"
    • ClientId="MyClientID"
    • Scope="fullAccess"
    • ClientSecret="MyClientSecret"
    • CallBackURL="https://thiscomponent.com/api"
    • AuthCode=""
  • >
    • <TokenRequest Url="http://tokenrequestserver.com/api/auth/login">
      • <RequestParameters>
        • <Parameter Name="HeaderFieldName" Value="HeaderFieldValue"/>
      • </RequestParameters>
      • <ResponseParameters>
        • <Parameter Name="AuthToken" Path="HeaderFieldName" From="Header" Value="">
      • </ResponseParameters>
    • </TokenRequest>
    • <ResourceRequest>
      • <RequestParameters>
        • <Parameter Name="HeaderFieldName" Path='AuthToken' From="TokenRequest" Value=""/>
      • </RequestParameters>
    • </RefreshTokenRequest>
  • </Authentication>

  XML element/ XML attribute	Value	Mandatory
  Authentication
  Name	The name of the authentication definition. The name is used to identify the authentication definition in other parts of the XML specification.	yes
  Type	OAuth	yes
  Flow	Custom	yes
  Method	Dynamic	yes
  ClientId	The client ID provided by the third-party vendor for access to the RESTful services. For security reasons you should specify at least the user password as a link to a server variable as a link to a server variable instead of using plain text. The server variable is stored encrypted in the server alias of the Alfabet Server.	yes
  ClientSecret	The client secret provided by the third-party vendor for access to the RESTful services.	yes
  CallBackURL	The URL the request is redirected to after authentication to process the request. The callback URL is also referred to as redirect Uri and is provided by the third-party vendor for access to the RESTful services.	yes
  Scope	If the third-party component limits access to functionality via Oauth2 via scopes, specify a scope defined for the client ID.	depending on third party vendor
  AuthCode	If the third-party component bases access on an authorization code provided to you, enter the code. Otherwise leave this field empty.	depending on third party vendor
  TokenRequest
  URL	Enter the URL for sending token requests as provided by the third-party component vendor.	yes
  TokenRequest > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the token request to the third-party component.	yes
  Name and Value	Define the name and the value for each field in a separate XML element Parameter.	yes
  TokenRequest > ResponseParameters > Parameter	The response parameter definition establishes a temporary storage of values returned by the token request call. The values are required for the subsequent ressource request, that means for the call to the callback URL for data transmission. Usually, the token is the only parameter that needs to be defined.	yes
  Name	Enter a name for the variable used to temporarily store the returned value.	yes
  From	Header	yes
  Path	The name of the request return header field containing the value.	yes
  Value	Leave this XML attribute empty.
  ResourceRequest > RequestParameters > Parameter	Specify the authentication header fields required for authentication in the data transmission calls after token request. For each header field, an XML element Parameter must be defined, Usually, only the token needs to be defined.	yes
  Name	The name of the resource request header field.	yes
  From	TokenRequest	yes
  Path	The name of the variable defined for temporary storage of the value from the token response with the XML attribute Name in the XML element TokenRequest > ResponseParameters > Parameter.	yes
  Value	Leave this XML attribute empty.	yes

• OAuth2 Authentication with Authorization

  The authentication tokens of the third-party component must match the standard authentication definitions. You can view the standard at https://www.oauth.com.

  OAuth2 authentication requests a new token in a configurable time interval.

  Set the following parameters in the Authentication XML element:

  • <Authentication
    • Name="OAuth2AuthenticationForMyApp"
    • Type="OAuth2"
    • Flow="AuthorizationCode"
    • ClientId="MyClientID"
    • Scope="fullAccess"
    • ClientSecret="MyClientSecret"
    • CallBackURL="https://thiscomponent.com/api"
    • AuthCode=""
  • >
    • <Authorization Url="https://thiscomponent.com/oauth2/authorize">
      • <RequestParameters>
        • <Parameter Name="client_id" Value="MyClientID"/>
        • <Parameter Name="response_type" Value="Assertion"/>
        • <Parameter Name="state" Value="State"/>
        • <Parameter Name="scope" Value="ApplicableScope"/>
        • <Parameter Name="callbackURL" Value="https://thiscomponent.com/api"/>
      • </RequestParameters>
    • </Authorization>
    • <TokenRequest Url="https://app.vssps.visualstudio.com/oauth2/token">
      • <RequestParameters>
        • <Parameter Name="client_assertion_type" Value="urn:ietf:params:oauth:client-assertion-type:jwt-bearer"/>
        • <Parameter Name="client_assertion" Value="{ClientSecret}"/>
        • <Parameter Name="grant_type" Value="urn:ietf:params:oauth:grant-type:jwt-bearer"/>
        • <Parameter Name="assertion" Value="{AuthCode}"/>
        • <Parameter Name="redirect_uri" Value="{CallBackURL}"/>
      • </RequestParameters>
    • </TokenRequest>
    • <RefreshTokenRequest Url="https://app.vssps.visualstudio.com/oauth2/token">
      • <RequestParameters>
        • <Parameter Name="client_assertion_type" Value="urn:ietf:params:oauth:client-assertion-type:jwt-bearer"/>
        • <Parameter Name="client_assertion" Value="{ClientSecret}"/>
        • <Parameter Name="grant_type" Value="refresh_token"/>
        • <Parameter Name="assertion" Value="{RefreshToken}"/>
        • <Parameter Name="redirect_uri" Value="{CallBackURL}"/>
      • </RequestParameters>
    • </RefreshTokenRequest>
  • </Authentication>

  XML element/ XML attribute	Value	Mandatory
  Authentication
  Name	The name of the authentication definition. The name is used to identify the authentication definition in other parts of the XML specification.	yes
  Type	OAuth2	yes
  Flow	AuthorizationCode	yes
  ClientId	The client ID provided by the third-party vendor for access to the RESTful services. For security reasons you should specify at least the user password as a link to a server variable instead of using plain text. The server variable is stored encrypted in the server alias of the Alfabet Server.	yes
  ClientSecret	The client secret provided by the third-party vendor for access to the RESTful services.	yes
  CallBackURL	The URL the request is redirected to after authentication to process the request. The callback URL is also referred to as redirect Uri and is provided by the third-party vendor for access to the RESTful services.	yes
  Scope	If the third-party component limits access to functionality via Oauth2 via scopes, specify a scope defined for the client ID.	depending on third party vendor
  AuthCode	If the third-party component bases access on an authorization code provided to you, enter the code. This	depending on third party vendor
  Authorization
  URL	Enter the URL for authorization requests to the RESTful service of the third-party component.	yes
  Authorization > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the authorization call to the third-party component for requesting authorization parameters. Specify one XML element Parameter for each header field.
  Name and Value	Define the name and the value for the header field. Usually, the values for the header fields are identical to the values you defined in the XML element Authentication . You can take these values over by specifying the respective XML attribute name in curly brackets. For example, defining Value={ClientID} will set the value to the client id defined in the XML element Authentication.	yes
  TokenRequest
  Url	Enter the URL for token requests to the RESTful service of the third-party component.	yes
  TokenRequest > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the token request to the third-party component. Specify one XML element Parameter for each header field.
  Name and Value	Define the name and the value for the header field. Usually, the values for the header fields are identical to the values you defined in the XML element Authentication . You can take these values over by specifying the respective XML attribute name in curly brackets. For example, defining Value={ClientID} will set the value to the client id defined in the XML element Authentication.	yes
  RefreshTokenRequest
  URL	Enter the URL for token refresh requests to the RESTful service of the third-party component.	yes
  RefreshTokenRequest > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the token refresh request to the third-party component. Specify one XML element Parameter for each header field.
  Name and Value	Define the name and the value for the header field. Usually, the values for the header fields are identical to the values you defined in the XML element Authentication . You can take these values over by specifying the respective XML attribute name in curly brackets. For example, defining Value={ClientID} will set the value to the client id defined in the XML element Authentication.	yes

• OAuth2 Authentication with Password Grant

  According to the OAuth standard specification password grant is deprecated and should not be used for connections between components for security reasons. OAuth2 authentication with authorization is the preferred method.

  The authentication tokens of the third-party component must match the standard authentication definitions. You can view the standard at https://www.oauth.com.

  OAuth2 authentication requests a new token in a configurable time interval.

  Set the following parameters in the Authentication XML element:

  • <Authentication
    • Name="OAuth2AuthenticationForMyApp"
    • Type="OAuth2"
    • Flow="PasswordGrant"
    • ClientId="MyClientID"
    • Scope="fullAccess"
    • ClientSecret="MyClientSecret"
    • CallBackURL="https://myComponent.com/api"
    • AuthCode=""
  • >
    • <TokenRequest Url="https://myComponent.com/oauth2/token">
      • <RequestParameters>
        • <Parameter Name="client_assertion_type" Value="urn:ietf:params:oauth:client-assertion-type:jwt-bearer"/>
        • <Parameter Name="client_assertion" Value="{ClientSecret}"/>
        • <Parameter Name="grant_type" Value="urn:ietf:params:oauth:grant-type:jwt-bearer"/>
        • <Parameter Name="assertion" Value="{AuthCode}"/>
        • <Parameter Name="redirect_uri" Value="{CallBackURL}"/>
      • </RequestParameters>
    • </TokenRequest>
    • <RefreshTokenRequest Url="https://myComponent.com/oauth2/token">
      • <RequestParameters>
        • <Parameter Name="client_assertion_type" Value="urn:ietf:params:oauth:client-assertion-type:jwt-bearer"/>
        • <Parameter Name="client_assertion" Value="{ClientSecret}"/>
        • <Parameter Name="grant_type" Value="refresh_token"/>
        • <Parameter Name="assertion" Value="{RefreshToken}"/>
        • <Parameter Name="redirect_uri" Value="{CallBackURL}"/>
      • </RequestParameters>
    • </RefreshTokenRequest>
  • </Authentication>

  XML element/ XML attribute	Value	Mandatory
  Authentication
  Name	The name of the authentication definition. The name is used to identify the authentication definition in other parts of the XML specification.	yes
  Type	OAuth2	yes
  Flow	PasswordGrant	yes
  ClientId	The client ID provided by the third-party vendor for access to the RESTful services. For security reasons you should specify at least the user password as a link to a server variable instead of using plain text. The server variable is stored encrypted in the server alias of the Alfabet Server.	yes
  ClientSecret	The client secret provided by the third-party vendor for access to the RESTful services.	yes
  CallBackURL	The URL the request is redirected to after authentication to process the request. The callback URL is also referred to as redirect Uri and is provided by the third-party vendor for access to the RESTful services.	yes
  Scope	If the third-party component limits access to functionality via Oauth2 via scopes, specify a scope defined for the client ID.	depending on third party vendor
  AuthCode	If the third-party component bases access on an authorization code provided to you, enter the code. This	depending on third party vendor
  TokenRequest
  Url	Enter the URL for token requests to the RESTful service of the third-party component.	yes
  TokenRequest > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the token request to the third-party component. Specify one XML element Parameter for each header field. User name and password must be defined in the token request.
  Name and Value	Define the name and the value for the header field. If a value for a header field is identical to a value you defined in the XML element Authentication , you can take the value over by specifying the respective XML attribute name in curly brackets. For example, defining Value={ClientID} will set the value to the client id defined in the XML element Authentication.	yes
  RefreshTokenRequest
  URL	Enter the URL for token refresh requests to the RESTful service of the third-party component.	yes
  RefreshTokenRequest > RequestParameters > Parameter	Specify the RESTful service header fields which need to be included in the token refresh request to the third-party component. Specify one XML element Parameter for each header field. User name and password must be defined in the token request.
  Name and Value	Define the name and the value for the header field. If a value for a header field is identical to a value you defined in the XML element Authentication , you can take the value over by specifying the respective XML attribute name in curly brackets. For example, defining Value={ClientID} will set the value to the client id defined in the XML element Authentication.	yes