Skip to main content

Resource Owner Password Flow and Introspect API

Click this button to view the example in Postman:

Run in Postman

In this use case an external service, possible another API, wishes to use onePortal's user directory for authentication. It also wants to avoid using onePortal web authentication.

Requirements for the external service:

  • Has registered itself as a confidential OpenID Client in the onePortal service. It must have the clientid and clientsecret values.
  • The client configuration should have "Generate Access Token as a signed JWT" enabled. This adds more metadata into the access token itself, which the external service or the end user may read.
  • A onePortal administrator must enable Password Grant for this client.
  • The service must be able to receive the username and password values from its clients to use during access token generation.
  • The service will use the Bearer tokens for user authentication.

Pre-requirements:

  • Users of the external service have onePortal User accounts. They have an username and a password.

Step 1​

The external service's users wish to use the external service. They need an access token. To do this, they will call the external service's login endpoint, and will give their current username and password in this request.

The external service will now check if the username and password are valid by requesting an access token from onePortal.

If onePortal accepts the username, password, and the client credentials, it will return an access token, a refresh token, expiration time, and other metadata. The external service should return the access token to the user. It should also inform the user of the expiration time, and encourage them to re-use the token for performance reasons.

The example request shows the parameters and authentication needed to convert the username and password into an access token.

Request​

POST /openid/token? HTTP/1.1
Host: {{oneportal-server}}
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {{base64(client_id:client_secret)}}

grant_type=password&username={{username}}&password={{password}}

Response​

{
    "access_token": "eyJraWQiOiJTa....3yNlGaq574",
    "token_type": "Bearer",
    "expires_in": 604799,
    "refresh_token": "xCMj...foZ8"
}

Step 2​

The external service's user wishes to use a specific API. They now have an access token. They call such an API and pass the access token in the request, for example in the Authorization header with a value like "Bearer abcd1234".

The external service will now have to verify this access token. It can

  • Parse the access token, and verify the 'aud' value which should match the client_id (if the JWT option was selected in client configuration); this quick check verifies that the user's access token is indeed intended for this service and not for some other onePortal client, however it does not verify that the token is valid
  • Call the onePortal introspect API to verify that the access token is valid and active

The example request shows the parameters and authentication needed to perform the introspect call.

Introspect request​

POST /openid/introspect HTTP/1.1
Host: {{oneportal-server}}
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {{base64(client_id:client_secret)}}

token=eyJra...fYDAQZthnKA&token_type_hint=access_token

Introspect response​

{
    "active": true,
    "clientId": "2915...4846",
    "username": "user1234",
    "tokenType": "access_token",
    "exp": 1555758374,
    "sub": "58cfb...ec5f"
}