...

In case of an error condition, depending on the error type, an error message will either be displayed directly to the end user (if there is a problem with the client ID or redirect URI), or it will be provided as an error parameter in the fragment component of the redirect URI to the client. See the specification section 4.2.2.1 for details.

The format of the access token and error response objects is as described above for the Authorization Code Grant. However, no refresh token is supplied.

Resource Owner Password Credentials

The Resource Owner Password Credentials flow allows client to obtain an access token using resource owner's credentials (username and password). The Password grant is one of the simplest OAuth grants and involves only one step: client uses resource owner's username and password to make POST request to the server to exchange password for access token.   This authorization grant type requires that the application collect the user’s password.

...

scope (optional) (the same in scope description above).

...

The response to the POST request is a JSON object (MIME type "application/json") like this:

...

format of the access token and error response objects is as described above for the Authorization Code Grant.

Client Credentials Grant flow

...

Authentication must be provided in the Authorization header as described for the Authorization Code Grant under client authentication.

Access code response

The response to the POST request is a JSON object (MIME type "application/json") like this:

{
    "access_token": "3e8ec1a3d43c983b57df0616b498c04807b466e919999aa0f3f3aabca1dd48cc",
    "token_type": "Bearer",
    "expires_in": "14400"
}

The access_token field contains the actual access token. The token_type will always be "Bearer" in Keycloak implementation. The number of seconds that the token is valid is given in expires_in.

Error response

In case of an error condition Keycloak responds with a HTTP 400 status code with the error message included in the body of the response as a JSON object, e.g.:

{  
    "error": "invalid_grant",
    "error_description": "Invalid authorization code."
}

For further details see section 5.2 of the specification.

https://www.keycloak.org/docs/latest/securing_apps/index.html#validating-access-tokens

Validating the access token

Keycloack provides a mechanism for validating access token. There are two ways to approach it - using Introspection Endpoint and validating tokens locally. See Keycloack documentation for more details. 

Using Introspection Endpoint

In order to manually validate a token issued by Keycloack, invoke Introspection Endpoint  /realms/{realm-name}/protocol/openid-connect/token/introspect

Please note that this endpoint can only be invoked by confidential clients (see OAuth 2 documentation for details).

To validate a token, make a POST request with parameters sent as "application/x-www-form-urlencoded" data to the Introspection Endpoint (see above) with the following query parameters included:

introspection. Might take 2 possible values: access_token or refresh_token. 

The response is a JSON object (MIME type "application/json") like this:

{
    "active": true,
    "scope": "document",
    "client_id": "l238j323ds-23ij4",

    "user_name": "jdoe",

    "token_type": "bearer"

    "exp": 1419356238,        

    "iat": 1419356238,    

    "nbf": 1419350238

}

Local validation

Due to the fact that Keycloack issued tokens are JWT digitally signed and encoded using JWS, access token can be locally validated using public key of the issueing realm. The realm’s public key can be be looked-up and cached using the certificate endpoint with the Key ID (KID) embedded within the JWS.

Certificate endpoint is: /realms/{realm-name}/protocol/openid-connect/certs. It returns public keys enabled by realm encoded as JSON Web Key (JWK). 

Refreshing an access token

Refresh tokens can be used to obtain a new access token without asking for the end user's consent. Access tokens expire after 4 hours unless they are revoked. Refresh tokens are valid for 180 days or until they are used to obtain a new access token.

To refresh an access token (server-side flow only) the client's server makes a POST request to the token endpoint with the following parameters included ("application/x-www-form-urlencoded" format):

grant_type (required): Must be set to "refresh_token".

refresh_token (required): The previously obtained refresh token.

The format of the response is identical to the one returned when the original access token was obtained:

...

The format of the access token and error response objects is as described above for the Authorization Code Grant.

Validating the access token

Keycloack provides a mechanism for validating access token. There are two ways to approach it - using Introspection Endpoint and validating tokens locally. See Keycloack documentation for more details. 

Using Introspection Endpoint

In order to manually validate a token issued by Keycloack, invoke Introspection Endpoint  /realms/{realm-name}/protocol/openid-connect/token/introspect

Please note that this endpoint can only be invoked by confidential clients (see OAuth 2 documentation for details).

To validate a token, make a POST request with parameters sent as "application/x-www-form-urlencoded" data to the Introspection Endpoint (see above) with the following query parameters included:

introspection: takes one of two possible values: access_token or refresh_token. 

The response is a JSON object (MIME type "application/json") like this:

{
    "active": true,
    "scope": "document",
    "client_id": "l238j323ds-23ij4",

    "user_name": "jdoe",

    "token_type": "bearer"

    "exp": 1419356238,        

    "iat": 1419356238,    

    "nbf": 1419350238

}

Local validation

Due to the fact that Keycloack issued tokens are JWT digitally signed and encoded using JWS, access token can be locally validated using public key of the issueing realm. The realm’s public key can be be looked-up and cached using the certificate endpoint with the Key ID (KID) embedded within the JWS.

Certificate endpoint is: /realms/{realm-name}/protocol/openid-connect/certs. It returns public keys enabled by realm encoded as JSON Web Key (JWK). 

Refreshing an access token

Refresh tokens can be used to obtain a new access token without asking for the end user's consent. Access tokens expire after 4 hours unless they are revoked. Refresh tokens are valid for 180 days or until they are used to obtain a new access token.

To refresh an access token (server-side flow only) the client's server makes a POST request to the token endpoint with the following parameters included ("application/x-www-form-urlencoded" format):

grant_type (required): Must be set to "refresh_token".

refresh_token (required): The previously obtained refresh token.

The format of the response is identical to the one returned when the original access token was obtained.

Note that a new refresh token is also issued with the response, so the old refresh token must be discarded by the client and replaced by the new token.

In case of an error condition, e.g. if the refresh token is no longer valid, the response will follow the same structure as for other token endpoint errors. The client should discard the refresh token and obtain a new access token using the server-side flow.

Access and refresh tokens configuration 

Keycloak provides a possibility to configure different lifespan for access token and refresh token. This is all done on the Tokens tab in the Keyclock. Expiration time can be configured for:

• Access token in Access Token Lifespan field
• Refresh token in SSO Session Idle field  field
  

See Session and Token Timeouts for more detailed information. 

Using an access token to access the Archie API

...