Maskinporten Client¶

Status: Opt-In Open Beta

This feature is only available in the Google Cloud Platform (GCP) clusters.

Abstract¶

Maskinporten allows API providers (external agencies) to define access to their APIs, modeled as scopes and based on the organization number.

Maskinporten is a service that offers a simple API security model based on the OAuth2 protocol, and the use of JWT bearer grants. A Concept inspired by Google's System Accounts.

The NAIS platform provides support for simple declarative provisioning of an Maskinporten client that your application may use to integrate with Maskinporten.

An Maskinporten client allows your application to leverage Maskinporten for authentication and authorization when performing service-to-service requests to external agencies. To achieve this, your application must implement JWT grants.

Configuration¶

Getting Started¶

Minimal nais.yaml example

apiVersion: "nais.io/v1alpha1"
kind: "Application"
metadata:
   name: nais-testapp
   namespace: aura
   labels:
       team: aura
spec:
  image: navikt/nais-testapp:66.0.0
  maskinporten:
    enabled: true
    scopes:
      - scope: "nav:some/scope"

Spec¶

See the NAIS manifest.

Access Policies¶

The following outbound external hosts are automatically added when enabling this feature:

ver2.maskinporten.no in development
maskinporten.no in production

You do not need to specify these explicitly.

Scopes¶

Maskinporten allows API providers to define access to their APIs, modeled as scopes and based on the consumer's organization number.

When a client requests a token from Maskinporten: - Maskinporten validates the validity of the JWT and signature (Runtime JWK Secret used to sign the JWT).
- When client has access to the requested resources: scope, an access_token will be returned to the client and can be used for further actions.

Danger

Make sure that the relevant service providers have pre-registered NAV as a valid consumer of any scopes that you define. Provisioning of client will fail otherwise. NAV´s pre-registered scopes can be found with proper access rights in Digdir selvbetjening.

Usage¶

Runtime Variables and Credentials¶

The following environment variables and files (under the directory /var/run/secrets/nais.io/maskinporten) are available at runtime:

Example values

Name	Values
`MASKINPORTEN_CLIENT_ID`	`e89006c5-7193-4ca3-8e26-d0990d9d981f`
`MASKINPORTEN_SCOPES`	`nav:first/scope nav:another/scope`
`MASKINPORTEN_WELL_KNOWN_URL`	`https://ver2.maskinporten.no/.well-known/oauth-authorization-server`

Example value for MASKINPORTEN_CLIENT_JWK

{
"use": "sig",
"kty": "RSA",
"kid": "jXDxKRE6a4jogcc4HgkDq3uVgQ0",
"alg": "RS256",
"n": "xQ3chFsz...",
"e": "AQAB",
"d": "C0BVXQFQ...",
"p": "9TGEF_Vk...",
"q": "zb0yTkgqO...",
"dp": "7YcKcCtJ...",
"dq": "sXxLHp9A...",
"qi": "QCW5VQjO..."
}

Legacy¶

This section only applies if you have an existing client registered at the IaC repository

Migration guide to keep existing Maskinporten client (NAIS application only)¶

The following describes the steps needed to migrate a client registered in IaC repository.

Step 1 - Update your client description in the IaC repository¶

Ensure the description of the client registered in the IaC repository follows the naming scheme:

<cluster>:<metadata.namespace>:<metadata.name>

Step 3 - Deploy your NAIS application with Maskinporten provisioning enabled¶

See getting started.

Step 4 - Delete your application from the IaC repository¶

Verify that everything works after the migration
Delete the application from the IaC repository in order to maintain a single source of truth.

Internals¶

See ID-porten internals.