OAuth: Client Authentication with the Platform's OAuth Provider

This topic provides information and examples for authenticating when using the platform's OAuth Provider. It includes:

Types of OAuth Clients supported

There are two types of OAuth client supported by the platform’s OAuth Provider:

  • Public: Public clients are those clients that do not need to be authenticated in order to obtain access tokens.
  • Confidential: All confidential clients must be authenticated at the Token API to obtain an access token, using one of the supported authentication methods given below.

Confidential Clients: Types of authentication supported

All confidential clients must be authenticated at the Token API to obtain an access token. The platform's OAuth 2.0 Token API supports the following authentication methods:

HTTP Basic Authentication

Basic authentication requires that users provide a valid user name and password to access content. All major browsers support this authentication method and it works across firewalls and proxy servers. The disadvantage of Basic authentication is that it transmits passwords across the network using weak encryption. You should use Basic authentication only when you know that the connection between the client and the server is secure.

With HTTP Basic authentication, the client sends its credentials via an HTTP Authorization Header with scheme Basic as shown in the example below.

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Form-Based Authentication

Form-based authentication works well for sites or applications on public web servers that receive many requests.

With this type of authentication, the client sends its credentials as part of the parameters. Depending on the HTTP method used to invoke the token API, the credentials might be sent in either of these ways:

  • query parameters
  • form-post

An example is below.

client_id=[Client ID]&client_secret=[Client shared secret]

HTTPS 2-way Authentication

HTPS 2-way authentication requires that both the client and server authenticate each other with certificates.

To use this form of authentication, the client must access the Token API over HTTPS. The client must send its X509 certificate as the client cert during HTTPS negotiation. The Authorization Server uses the client certificate to identify the client uniquely within the platform, thus completing the authentication.

JWT Authentication

JWT Authentication is an extension mechanism in which JWT assertion will be used as client credentials. The client must include the assertion and related information using the following HTTP request parameters.

Parameter Description
client_assertion_type The format of the assertion as identified by the Authorization Server. The value must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion The assertion being used to authenticate the client. Only JWT compact serialization is allowed.

The JWT assertion must be signed using a symmetric signature algorithm or an asymmetric signature algorithm.

If the Client chooses to sign the JWT using a symmetric signature algorithm such as HS256, the client secret must be used as the cryptographic key.

If the Client signs the JWT using an asymmetric signature algorithm such as RS256, the client must use its private key as the cryptographic key and must upload the corresponding public key certificate in the Akana platform so as to verify the signatures at the Token API.

Below is an example of a JWT token (decoded form) used for client credentials.

JWT token header: 

{
"alg": "HS256"
}

JWT token body: 

{
  "exp": 1436268156,
  "sub": "devconsole",
  "nbf": 1436267256,
  "aud": [
    "http://acmepaymentscorp/oauth/oauth20/token"
  ],
  "iss": "devconsole",
  "jti": "ffr45freui360aseqdh5",
  "iat": 1436267256
}

JWT token signature: 

IFlwboCnB50gCMgAa3jC42kKppRvuHitN-j3vYuxG48

Example JWT token in compact serialization form 

eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0MzYyNjgxNTYsInN1YiI6ImRldmNvbnNvbGUiLCJuYmYiO
jE0MzYyNjcyNTYsImF1ZCI6WyJodHRwOlwvXC9hYnVqYWdvbmRhLTY0MzA6OTkwMFwvb2F1dGhcL29
hdXRoMjBcL3Rva2VuIl0sImlzcyI6ImRldmNvbnNvbGUiLCJqdGkiOiJmZnI0NWZyZXVpMzYwYXNlc
WRoNSIsImlhdCI6MTQzNjI2NzI1Nn0.IFlwboCnB50gCMgAa3jC42kKppRvuHitN-j3vYuxG48

Example token request using a JWT assertion as client credentials 

grant_type=authorization_code&code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciO...[omitted for brevity]...48

Requesting an access token using the Authorization Code Grant Type

Operation: POST /oauth/oauth10/token or GET /oauth/oauth10/token.

To request an access token using the Authorization Code grant type, the client must have already obtained the Authorization Code from the authorization server.

An Authorization Code is a short-lived token issued to the client application by the authorization server upon successful authentication/authorization of an end-user (resource owner). The client application then uses the authorization code to request an access token from the authorization server.

Request

Header Description
URL {oauth-provider-base-url}/oauth/oauth20/token
Action GET/POST
Request Headers Accept: application/json

Request Parameters

Header Description
client_id Unique identifier of the client application.
client_secret The client secret value; this value identifies the client with the provider.
grant_type The grant type. The value must be set to authorization_code.
code

The authorization code.

It is the authorization code that was previously received by the client application after user authentication..
redirect_uri

OAuth 2.0: standard redirect_uri parameter. The redirect URI configured by the app. For more information, see OAuth Parameters.

It is the redirect URI where the client received the authorization code.
X_proxy_azp_client_id Optionally, the client can send this parameter with the value of actual authorized party so it will be used in the ID token claims azp and aud.

Example

client_id=xyzclient&client_secret=xyzsecret&grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Requesting an access token using the Client Credentials Grant Type

The client can request an access token using only its client credentials (or other supported means of authentication; refer to Confidential Clients: Types of Authentication Supported above) when the client is requesting access to the protected resources under its control.

Request

Header Description
URL {oauth-provider-base-url}/oauth/oauth20/token
Action GET/POST
Request Headers Accept: application/json

Request Parameters

Header Description
client_id Unique identifier of the client application.
client_secret The client secret value; this value identifies the client with the provider.
grant_type The grant type. The value must be set to client_credentials.
scope

OAuth 2.0: standard scope parameter. One or more scopes configured in the OAuth provider. Space separator for multiple scopes.

The scope of the access request.

Example

client_id=xyzclient&client_secret=xyzsecret&grant_type=client_credentials&scope=READ%20profile%20email

Requesting an access token using the Resource Owner Password Credentials Grant Type

To request an access token using the Resource Owner Password Credentials grant type, the client must already have the password credentials from the resource owner.

This grant type is suitable for clients capable of obtaining the resource owner's credentials (username and password, typically using an interactive form).

Request

Header Description
URL {oauth-provider-base-url}/oauth/oauth20/token
Action GET/POST
Request Headers Accept: application/json

Request Parameters

Header Description
client_id Unique identifier of the client application.
client_secret The client secret value; this value identifies the client with the provider.
grant_type The grant type. The value must be set to password.
username The resource owner's username.The resource owner's username.
password The resource owner's password.
scope

OAuth 2.0: standard scope parameter. One or more scopes configured in the OAuth provider. Space separator for multiple scopes.

The scope of the access request.

Example

client_id=xyzclient&client_secret=xyzsecret&grant_type=password&username=jdoe&password=s3cret&scope=READ%20profile%20email

Requesting an access token using the Refresh Token Grant Type

To request for access token using the refresh token grant type, the client must have already obtained the refresh token from the authorization server.

A Refresh Token is a credential used to obtain an access token from an authorization server. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires.

A refresh token is a string representing the authorization granted to the client by the resource owner. The string is usually opaque to the client. The token denotes an identifier used to retrieve the authorization information.

Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers.

Request

Header Description
URL {oauth-provider-base-url}/oauth/oauth20/token
Action GET/POST
Request Headers Accept: application/json

Request Parameters

Header Description
client_id Unique identifier of the client application.
client_secret The client secret value; this value identifies the client with the provider.
grant_type The grant type. The value must be set to refresh_token.
refresh_token The refresh token.

Example

client_id=xyzclient&client_secret=xyzsecret&grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

Requesting an access token using the JWT Bearer Assertion Grant Type

To request an access token using this grant type, the client must have already obtained the JWT Assertion from an issuer.

Upon successful validation of the JWT assertion, The authorization server issues an access token to the client.

Request

Header Description
URL {oauth-provider-base-url}/oauth/oauth20/token
Action GET/POST
Request Headers Accept: application/json

Request Parameters

Header Description
client_id Unique identifier of the client application.
client_secret The client secret value; this value identifies the client with the provider.
grant_type The grant type. The value must be set to urn:ietf:params:oauth:grant-type:jwt-bearer.
refresh_token The refresh token.
assertion JWT Bearer Assertion grant type only: The JWT Bearer Assertion.

Example

client_id=xyzclient&client_secret=xyzsecret&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ. ewogImlzc
[...omitted for brevity...].ggW8hZ1EuVLux[...omitted for brevity...]

Access token response

The response is the access token.

Sample Response

{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
    NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
    fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
    AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
    Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
    NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
    QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
    K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
    XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

The access token response includes the following information:

Response Parameters

Parameter Description
access_token The access token.
token_type The token type. Values supported by the platform's OAuth Provider: Bearer or MAC.
refresh_token The Refresh Token. Refresh tokens may be issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires. A refresh token is a string representing the authorization granted to the client by the resource owner. The string is usually opaque to the client. The token denotes an identifier used to retrieve the authorization information. Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers.
expires_in The lifetime in seconds of the access token.
id_token The ID Token. The ID Token is a security token that contains Claims about the Authentication of an End-User by an Authorization Server when using a Client, and potentially other requested Claims. The ID Token is represented as a JWT.