Resource Owner Password Credentials Grant

The resource owner password credentials is described in the rfc 6749. The password credentials should only be used when there is a trust relationship with the OAuth client. This imply generally that the application is part of the device operating system or is an highly trusted application (eg: Android official application). This grant needs both client credentials set and resource owner credentials set.

The flow is described in the following chart:

Step 1: Resource credentials

To access the resources, the application should be granted with the resource owner credentials. The credentials can be obtained through a login page displayed by the OAuth client (such as in a mobile application).

Step 2: Call the token endpoint

The final step to get an access token is the call to the /token endpoint to exchange the resource owner credentials for an access token. Once the token is retrieved, the best practice should be to discard the resource owner credentials.

The client credentials should also be passed in the http Authorization header by using basic authentication. The client_secret should remain a secret!

See the example below, in which the resource credentials and the client credentials are used to get an access token:

curl -X POST -H "Authorization: Basic ZjY5ODljN2Y6N2RlMzE2Mjg4YjRlYjFkNTdlYTVhMTkwYWJiZWM2OGI=" -H "Content-Type: application/x-www-form-urlencoded" -d 'grant_type=password' -d 'username=johndoe&password=myComplexPsw!1' --data-urlencode 'scope=urn:axa.assistance.travel.countries.read_only' "https://apis.axa-assistance.com/auth/v1/token"
  • Authorization header: http basic authentication header, using the client id and client secret that was registered for that client in the development portal. In this example: Basic base64Encoding(f6989c7f:7de316288b4eb1d57ea5a190abbec68b).
  • Content-Type: application/x-www-form-urlencoded: Use this content type header that specifies the format of the following parameters in the body.
  • grant_type=password: Indicates that the password grant type is being used.
  • username=johndoe: User name of the resource owner
  • password=myComplexPsw!1: Password of the resource owner
  • scope=urn:axa.assistance.travel.countries.read_only: these scopes specify the access rights that have been granted to the access_token. In this case, the application will only get access to read the list of countries.

Step 3: Use the APIs

After calling the token endpoint in step 2, you will get a response with the following format:

{
  "access_token": "eyJ0eXAi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJ0eXAiOiJKV1QiLC...",
  "scope": "urn:axa.assistance.travel.countries.read_only",
  "id_token": "eyJ0eXAiOiJKV1QiLCJhb...",
  "id_token_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}

The access_token value is the one that will grant access to the apis. It’s actually a JWT. This token can be used to call the apis that are authorized by the scopes that this token was granted. You can find these scopes in the “scope” field in the response.

Let’s take a look at this jwt example.

It’s divided in 3 segments split by a “.”:

  • The first segment of the JWT contains the information regarding the signing algorithm.
  • The second segment contains the token information. There you will find the username in sub.value. As a unique ID to identify a user, we strongly suggest to use: customData.cn.

This access token can be safetly used from both server side or from javascript. To use it, you just need to add it to the authorization header using it as a bearer token.

  • The third segment contains the signature of the first and the second segment using the signing algorithm. The signature should always be verified to ensure that the data have not been tampered.

Example call:

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb......GciOiJSUzI1N" "https://apis.axa-assistance.com/travel/v1/countries"