Secure your API with Maskinporten¶
This how-to guides you through the steps required to secure your API using Maskinporten:
Prerequisites¶
- Expose your application to consumers at a publicly accessible domain.
Define scopes¶
A scope represents a permission that a given consumer has access to.
Declare all the scopes that you want to expose in your application's NAIS manifest:
spec:
maskinporten:
enabled: true
scopes:
exposes:
- name: "some.scope.read"
enabled: true
product: "arbeid"
- name: "some.scope.write"
enabled: true
product: "arbeid"
See the scope naming reference for details on naming scopes.
See the NAIS application reference for the complete specifications with all possible options.
Grant access to consumers¶
Grant the external consumer access to the scopes by specifying their organization number:
spec:
maskinporten:
enabled: true
scopes:
exposes:
- name: "some.scope.read"
...
consumers:
- orgno: "123456789"
Now that you have configured the scopes in Maskinporten, consumers can now request tokens with these scopes. You will now need to validate these tokens in your application.
Validate tokens¶
Verify incoming requests from consumers by validating the JWT Bearer token in the Authorization
header.
JWT Validation
Validating a JWT involves a number of steps. These steps are outlined and described below in a language- and framework-agnostic way.
Libraries for token validation
We recommend using a library in your language of choice to handle all the validation steps described below. Here are some recommended libraries:
- navikt/oasis (JavaScript)
- navikt/token-support (Java / Kotlin)
Validation is also supported by many popular frameworks:
- Ktor (Kotlin)
- Spring Security (Java / Kotlin)
To validate the token, start by validating the signature and standard time-related claims.
Additionally, perform the following validations:
Issuer Validation
Validate that the iss
claim has a value that is equal to either:
- the
AZURE_OPENID_CONFIG_ISSUER
environment variable, or - the
issuer
property from the metadata discovery document. The document is found at the endpoint pointed to by theAZURE_APP_WELL_KNOWN_URL
environment variable.
Audience Validation
Validate that the aud
claim is equal to the AZURE_APP_CLIENT_ID
environment variable.
Signature Validation
Validate that the token is signed with a public key published at the JWKS endpoint. This endpoint URI can be found in one of two ways:
- the
AZURE_OPENID_CONFIG_JWKS_URI
environment variable, or - the
jwks_uri
property from the metadata discovery document. The document is found at the endpoint pointed to by theAZURE_APP_WELL_KNOWN_URL
environment variable.
Claims Validation
Other claims may be present in the token. Validation of these claims is optional.
To validate the token, start by validating the signature and standard time-related claims.
Additionally, perform the following validations:
Issuer Validation
Validate that the iss
claim has a value that is equal to either:
- the
MASKINPORTEN_ISSUER
environment variable, or - the
issuer
property from the metadata discovery document. The document is found at the endpoint pointed to by theMASKINPORTEN_WELL_KNOWN_URL
environment variable.
Scope Validation
Validate that the scope
claim contains the expected scope(s).
The scope
claim is a string that contains a whitespace-separated list of scopes.
The semantics and authorization that a scope represents is up to you to define and enforce in your application code.
Audience Validation
The aud
claim is not included by default in Maskinporten tokens and does not need to be validated.
It is only included if the consumer has requested an audience-restricted token.
Only validate the aud
claim if you want to require your consumers to use audience-restricted tokens.
The expected audience value is up to you to define and must be communicated to your consumers.
The value must be an absolute URI (such as https://some-provider.no
or https://some-provider.no/api
).
Signature Validation
Validate that the token is signed with a public key published at the JWKS endpoint. This endpoint URI can be found in one of two ways:
- the
MASKINPORTEN_JWKS_URI
environment variable, or - the
jwks_uri
property from the metadata discovery document. The document is found at the endpoint pointed to by theMASKINPORTEN_WELL_KNOWN_URL
environment variable.
Other Token Claims
Other claims may be present in the token. Validation of these claims is optional.