/token endpoint
About
The /token endpoint is thoroughly documented in OpenID Connect Core, chapter 3.1.3
Request
The client requests a token by passing the authorization grant (normally a ‘code’ value) to the /token endpoint.
There are different parameters available for the request, depending on grant type and client authentication method. The following always apply:
| Parameter | Value |
|---|---|
| Http method | POST |
| Content-type | application/x-www-form-urlencoded |
Request parameters when using code grant
The following request parameters are available when using the authorization code grant
| Parameter | Requirement | Description |
|---|---|---|
| client_id | required | The identifier of the client |
| grant_type | required | Type of grant the client is sending, ie. authorization_code |
| code | required | The authorization code received in the authorization response. |
| redirect_uri | required | The desired redirect uri. Must be the same value as was used in the corresponding authentication request. |
| code_verifier | recommended | The PKCE code verifier. Mandatory for public clients. Between 43 and 128 characters (ASCII). |
| client_assertion_type | optional | If using certificate / asymmetric key for client authentication (recommended), this parameter must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
| client_assertion | optional | A JWT identifing the client, mandatory if client_assertion_type is set |
Request parameters when using JWT-bearer grant
The following request parameters are available when using the JWT bearer grant
| Parameter | Requirement | Description |
|---|---|---|
| grant_type | required | Type of grant the client is sending, ie. urn:ietf:params:oauth:grant-type:jwt-bearer |
| assertion | optional | The JWT grant |
There is no need to perform client authentication when using this grant, as the client is implicitly authenticated by the certificate in the JWT.
See JWT grant for requirements for the JWT grant.
Request parameters when using refresh_token grant
The following request parameters are available when using the refresh_token grant
| Parameter | Requirement | Description |
|---|---|---|
| grant_type | required | Type of grant the client is sending, ie. refresh_token |
| refresh_token | required | The refresh token |
Client authentication must be used with this grant. Client authentication methods client_secret_post or private_key_jwt adds parameters to the request. Client authentication method client_secret_basic uses the Authorization header. Client authentication method none cannot be used for the refresh_token grant.
Client authentication
ID-porten supports four client authentication methods:
- client_secret_basic
- client_secret_post
- private_key_jwt
- none
Client authentication using client secret basic
A previously exchanged out-of-band static secret is used for standard HTTP bacic authentication header comprised of base64 encoded concatenation of client_id + colon + secret.
POST /token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dGVzdF9ycF95dDI6cGFzc3dvcmQ=
grant_type=authorization_code&
redirect_uri=https%3A%2F%2Feid-exttest.difi.no%2Fidporten-oidc-client%2Fauthorize%2Fresponse&
code=1JzjKYcPh4MIPP9YWxRfL-IivWblfKdiRLJkZtJFMT0%3D
Client authentication using client secret post
A previously exchanged out-of-band static secret is used for authentication. The secret is added as a claim client_secret in the JSON payload of the POST request.
Client authentication using JWT token
The client generates a JWT as specified in RFC7523 chapter 2.2, and signs this using a valid business certificate conforming to Rammeverk for autentisering og uavviselighet i elektronisk kommunikasjon med og i offentlig sektor.
The request is extended with the attributes ‘client_assertion_type’ and ‘client_assertion’, see above.
The ‘sub’ field of the JWT must be set equal to your client_id, otherwise the JWT itself is similar to those used for JWT grants.
Example:
POST /token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4&
client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=< jwt >
No client authentication
Mobile apps and single-page applications are clients which cannot protect a secret/certificate and thus should be pre-registered to use no client authentication.
Use of PKCE and the state parameter will be required when using no client authentication.
Response
The response is a set of tokens and associated metadata, and will depend upon what was requested.
| Claim | Description |
|---|---|
| access_token | An Oauth2 access token, either by reference or as a JWT depending on which scopes was requested and/or client registration properties. |
| expires_in | Number of seconds until this access_token is no longer valid |
| id_token | An OpenID Connect id_token. Only returned if ‘openid’ scope was requested. |
| refresh_token | Issued to confidential clients |
| scope | The list of scopes issued in the access token. Included for convenience only, and should not be trusted for access control decisions. |
Example:
{
"access_token" : "IxC0B76vlWl3fiQhAwZUmD0hr_PPwC9hSIXRdoUslPU=",
"id_token" : "eyJraWQiOiJtcVQ1QTNMT1NJSGJwS3JzY2IzRUhHcnItV0lGUmZMZGFxWl81SjlHUjlzIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiItdi1sY2FlNXJHRy1qbHZ6dXY5WTlIN1I4Tm1BZU0yLWtoMHFXYi12UElFPSIsImF1ZCI6InRlc3RfcnBfeXQyIiwiYWNyIjoiTGV2ZWw0IiwiYXV0aF90aW1lIjoxNDk3NjA1MjE4LCJhbXIiOiJCYW5rSUQiLCJpc3MiOiJodHRwczpcL1wvb2lkYy15dDIuZGlmaS5lb24ubm9cL2lkcG9ydGVuLW9pZGMtcHJvdmlkZXJcLyIsInBpZCI6IjIzMDc5NDEwOTE4IiwiZXhwIjoxNDk3NjA1MzgyLCJsb2NhbGUiOiJuYiIsImlhdCI6MTQ5NzYwNTI2Miwibm9uY2UiOiJtaW5fZmluZV9ub25jZV92ZXJkaSIsImp0aSI6IkhnYjN6d085ZzBiam1TYkNDdFFDeE1vd3NaRXUwMGxDSjJFeGc0Wmh2M2c9In0.Pl9APC3_GGJBLYR3AqZRC8-fjOWdIW3eQAn2zbqstGEyv8AJ6yPLiH0EA4e1RgHxK-dPwtydJF0fV-1aiPjDGYM8d-saN26WBlRyvBRH1j8A9smQv5XxJoXssfxMr-t1ZB5wDM37MOkwMF4zTNPVmyeQ0qM0PAudG7ZpT0gWPksQIWOoSk4A--MoOHPBy41xXWSpOvUh3jBqrnWEcZpqS785Ufofc6cDfXk_wM_-EMAlS-UExMq-hH60nPwXmR0cBNW3GV2xm_frYyqBYnxXoELmzREijpeSyiELTqn2k4nwCjeiGDXXs_Nw12D2KpWLDctqqsUtTTRUhsnCPSoDng",
"token_type" : "Bearer",
"expires_in" : 599,
"refresh_token" : "yBtapz3ThC3uVWufWhxsLtbEidPnEsL7atvfHSBANDs=",
"scope" : "openid"
}
The id_token
The id_token is the assertion of the authenticated user identity. It tells you “who the user is”, but not “what the user can access”.
The id_token is documented here.
The access token
The access_token enables the client to access APIs on behalf of the authenticated user.