/token endpoint

About

Using JWT grants towards the /token endpoint is documented in RFC 7523, section 2.1 .

Request

The client requests a token by passing a JWT grant to the /token endpoint.

The following request body attributes shall be used when passing 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 constructing the JWT grant.

Example request:

POST /token HTTP/1.1
Host: test.maskinporten.no
Content-Type: application/x-www-form-urlencoded

assertion=<the grant>
&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer

Response

The response is a set of tokens and associated metadata, and will depend upon what was requested.

Please note that the access token is opaque for the client, and the format may be changed. Thus the client should not inspect/validate the token contents.

Example response:

{
  "access_token" : "IxC0B76vlWl3fiQhAwZUmD0hr_PPwC9hSIXRdoUslPU=",
  "token_type" : "Bearer",
  "expires_in" : 599,
  "scope" : "difitest:test1"
}

The access token

Maskinporten issues only self-contained tokens:

The token is a JWT with the following structure:

Access token header:

Access token body:

If the token was issued to a supplier acting on behalf of another organization, the token will also include the following two claims:

If the token is audience-restricted, the following claim will also be included:

If the token is enduser-restricted, the following claim will also be included:

Identifying organizations

ID-porten and Maskinporten use a forward-compatible notation for identifying organizations. This is because we expect that the solutions in the future will be extended handle both foreign organizations, organizations not having a registration in the Enhetsregisteret (i.e. “offentlige utvalg”) as well a sub-entities within an organization.

The ID-claim identifies the organization, which the authority-claim states how this identifier is encoded:

Customer implementations must thus be able to handle that the authority list and consequently the ID formatting may be extended in the future.

Below is an example for Digitaliseringsdirektoratet:

"consumer" : {
   "authority" : "iso6523-actorid-upis",
   "ID" : "0192:991825827"
 }

client_amr

The following values may be returned for the client_amr-claim. The values are partly from Oauth Token Endpoint Authentication Methods, plus some custom claims for certificate-based authentication:

Access token validation

The client and resource server MUST validate all responses from Maskinporten according to the Oauth2 standards as well as best practice recommendations from the IETF.

Access tokens must always be validated by the Resource Server / API before granting access. Some key steps in the validation are:

• verify that the issuer of the token is Maskinporten (iss=https://maskinporten.no/)
• verify that the token is signed
• verify that the signature is created by the signing keys of Maskinporten published at our /jwks-endpoint
  • you should cache the signing keys of Maskinporten for say 24 hours and avoid calling the /jwks-endpoint for each token validation.
• verify that the token contains the expected oauth2 scope

Clients should normally just pass the access token along to the resource server without any processing of it, however if any processing is performed, clients must also perform such validation.

The following references are vital:

• RFC6819: Oauth2 threat model
• Draft RFC: OAuth 2.0 Security Best Current Practice

Developers integrating towards Maskinporten are expected to know these documents and apply them in their risk assessments. Our documention will not re-iterate the recommendations in the above documents, but overall we would like to hightlight:

• Use a certified / well recognized IAM-product or Oauth2 library for the integration
• Keep keys / certificates safe to avoid getting your organization impersonated