ID-porten¶
ID-porten is a common log-in system used for logging into Norwegian public e-services for citizens.
NAIS provides a sidecar that integrates with ID-porten, so that you can easily and securely log in and authenticate citizen end-users.
Availability
The sidecar is only available in the Google Cloud Platform clusters.
Spec¶
Port Configuration
The sidecar will occupy and use the ports 7564
and 7565
.
Ensure that you do not bind to these ports from your application as they will be overridden.
Minimal example:
See the NAIS manifest reference for the complete specification.
Ensure that you also define at least one ingress for your application.
Network Connectivity¶
ID-porten is an external service. Outbound access to the ID-porten hosts is automatically configured by the platform.
You do not have to explicitly configure outbound access to ID-porten yourselves when using the sidecar.
Usage¶
Try out a basic user flow:
- Visit your application's login endpoint (
https://<ingress>/oauth2/login
) to trigger a login. - After logging in, you should be redirected back to your application.
- All further requests to your application should now have an
Authorization
header with the user's access token as a Bearer token - Visit your application's logout endpoint (
https://<ingress>/oauth2/logout
) to trigger a logout. - You will be redirected to ID-porten for logout, and then back to a preconfigured logout page.
- Success!
See Wonderwall for further usage details.
Runtime Variables & Credentials¶
Your application will automatically be injected with both environment variables and files at runtime. You can use whichever is most convenient for your application.
The files are available at the following path: /var/run/secrets/nais.io/idporten/
Name | Description |
---|---|
IDPORTEN_AUDIENCE |
The expected audience for access tokens from ID-porten. |
IDPORTEN_WELL_KNOWN_URL |
The URL for ID-porten's OIDC metadata discovery document. |
IDPORTEN_ISSUER |
issuer from the metadata discovery document. |
IDPORTEN_JWKS_URI |
jwks_uri from the metadata discovery document. |
These variables are used for token validation.
Security Levels¶
ID-porten classifies different user authentication methods into security levels of assurance.
This is reflected in the acr
claim for the user's JWTs issued by ID-porten.
Valid values, in increasing order of assurance levels:
Value | Description | Notes |
---|---|---|
idporten-loa-substantial |
a substantial level of assurance, e.g. MinID | Also known as Level3 |
idporten-loa-high |
a high level of assurance, e.g. BankID, Buypass, Commfides, etc. | Also known as Level4 |
To configure a default value for all login requests:
If unspecified, the sidecar will use idporten-loa-high
as the default value.
The sidecar automatically validates and enforces the user's authentication level matches or exceeds the application's configured level. The user's session is marked as unauthenticated if the level is lower than the configured level.
Example:
- If the application requires authentication on the
idporten-loa-substantial
level, the sidecar will allow sessions with a level ofidporten-loa-high
. - The inverse is rejected. That is, applications expecting
idporten-loa-high
authentication will have the sidecar mark sessions atacr=idporten-loa-substantial
as unauthenticated.
For runtime control of the value, set the query parameter level
when redirecting the user to login:
Locales¶
ID-porten supports a few different locales for the user interface during authentication.
Valid values shown below:
Value | Description |
---|---|
nb |
Norwegian Bokmål |
nn |
Norwegian Nynorsk |
en |
English |
se |
Sámi |
To configure a default value for all requests:
If unspecified, the sidecar will use nb
as the default value.
For runtime control of the value, set the query parameter locale
when redirecting the user to login:
Token Validation¶
The sidecar attaches an Authorization
header with the user's access_token
as a Bearer token, as long as the user is authenticated.
It is your responsibility to validate the token before granting access to resources.
For any endpoint that requires authentication; deny access if the request does not contain a valid Bearer token.
Always validate 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
IDPORTEN_ISSUER
environment variable, or - the
issuer
property from the metadata discovery document. The document is found at the endpoint pointed to by theIDPORTEN_WELL_KNOWN_URL
environment variable.
Audience Validation
Validate that the aud
claim is equal to the IDPORTEN_AUDIENCE
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
IDPORTEN_JWKS_URI
environment variable, or - the
jwks_uri
property from the metadata discovery document. The document is found at the endpoint pointed to by theIDPORTEN_WELL_KNOWN_URL
environment variable.
Other Token Claims¶
Other claims may be present in the token. Validation of these claims is optional.
Notable claims:
acr
(Authentication Context Class Reference)- The security level used for authenticating the end-user.
pid
(personidentifikator)- The Norwegian national ID number (fødselsnummer/d-nummer) of the authenticated end user.
For a complete list of claims, see the Access Token Reference in ID-porten.
Next Steps¶
The access token provided by the sidecar should only be accepted and used by your application.
To access other applications, you need a token scoped to the target application.
For ID-porten, use the token exchange grant (TokenX) to exchange the token for a new token.
Recommended: JavaScript Library
See https://github.com/navikt/oasis for an opinionated JavaScript library for token validation and exchange.