Prerequisites: You have access to the authentication parameters required to access the RESTful services as provided by the third-party vendor.

Alfabet's generic API integration interface supports HTTP, API Key, OAuth and OAuth2 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

  • 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

  • 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

  • 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

  • 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