Consume external API using Maskinporten¶

This how-to guides you through the steps required to consume an API secured with Maskinporten:

Configure your application¶

Declare all the scopes that you want to consume in your application's NAIS manifest so that your application is granted access to them:

spec:
  maskinporten:
    enabled: true
    scopes:
      consumes:
        - name: "skatt:some.scope"
        - name: "nav:some/other/scope"

The scopes themselves are defined and owned by the external API provider. The exact scope values must be exchanged out-of-band.

Finally, configure appropriate outbound access policies to access the external API endpoints.

Acquire token¶

To acquire a token, you can either:

• acquire tokens with Texas, or
• acquire tokens manually in your application

Acquire tokens with Texas¶

Send a HTTP POST request to the endpoint found in the NAIS_TOKEN_ENDPOINT environment variable. The request must have a Content-Type header set to either:

• application/json or
• application/x-www-form-urlencoded

The body of the request should contain the following parameters:

If the API provider requires the use of an audience-restricted token, you must also include the following parameter in the request:

POST ${NAIS_TOKEN_ENDPOINT} HTTP/1.1
Content-Type: application/json

{
    "identity_provider": "maskinporten",
    "target": "example:some.scope"
}

POST ${NAIS_TOKEN_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

identity_provider=maskinporten&
target=example:some.scope

{
    "access_token": "eyJra...",
    "expires_in": 3599,
    "token_type": "Bearer"
}

Your application does not need to validate this token.

Tokens are cached by default with regards to the expires_in field. To forcibly fetch a new token, set the skip_cache=true parameter in the request.

Acquire tokens manually¶

To acquire a token from Maskinporten, you will need to create a client assertion.

Create client assertion¶

The client assertion is a JWT that consists of a header, a payload and a signature.

The header should consist of the following parameters:

The payload should have the following claims:

If the API provider requires the use of an audience-restricted token, you must also include the following claim:

Finally, create a signature for the client assertion.

import com.nimbusds.jose.*
import com.nimbusds.jose.crypto.*
import com.nimbusds.jose.jwk.*
import com.nimbusds.jwt.*
import java.time.Instant
import java.util.Date
import java.util.UUID

val clientId: String = System.getenv("MASKINPORTEN_CLIENT_ID")
val clientJwk: String = System.getenv("MASKINPORTEN_CLIENT_JWK")
val issuer: String = System.getenv("MASKINPORTEN_ISSUER")
val scope: String = "nav:test/api"
val rsaKey: RSAKey = RSAKey.parse(clientJwk)
val signer: RSASSASigner = RSASSASigner(rsaKey.toPrivateKey())

val header: JWSHeader = JWSHeader.Builder(JWSAlgorithm.RS256)
    .keyID(rsaKey.keyID)
    .type(JOSEObjectType.JWT)
    .build()

val now: Date = Date.from(Instant.now())
val expiration: Date = Date.from(Instant.now().plusSeconds(60))
val claims: JWTClaimsSet = JWTClaimsSet.Builder()
    .issuer(clientId)
    .audience(issuer)
    .issueTime(now)
    .claim("scope", scope)
    .expirationTime(expiration)
    .jwtID(UUID.randomUUID().toString())
    .build()

val jwtAssertion: String = SignedJWT(header, claims)
    .apply { sign(signer) }
    .serialize()

import json, jwt, os, uuid
from datetime import datetime, timezone, timedelta
from jwt.algorithms import RSAAlgorithm

issuer = os.getenv('MASKINPORTEN_ISSUER')
jwk = os.getenv('MASKINPORTEN_CLIENT_JWK')
client_id = os.getenv('MASKINPORTEN_CLIENT_ID')

header = {
    "kid": json.loads(jwk)['kid']
}

payload = {
    "aud": issuer,
    "iss": client_id,
    "scope": "nav:test/api",
    "iat": datetime.now(tz=timezone.utc),
    "exp": datetime.now(tz=timezone.utc)+timedelta(minutes=1),
    "jti": str(uuid.uuid4())
}

private_key = RSAAlgorithm.from_jwk(jwk)
jwtAssertion = jwt.encode(payload, private_key, "RS256", header)

Request token from Maskinporten¶

Request

The token request is an HTTP POST request. It must have the Content-Type header set to application/x-www-form-urlencoded.

The body of the request should contain the following parameters:

Send the request to the token_endpoint, i.e. the URL found in the MASKINPORTEN_TOKEN_ENDPOINT environment variable:

POST ${MASKINPORTEN_TOKEN_ENDPOINT} HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=eY...

Response

Maskinporten will respond with a JSON object that contains the access token. Your application does not need to validate this token.

{
    "access_token": "eyJraWQ...",
    "expires_in": 3599,
    ...
}

See the Maskinporten token documentation for more details.

Consume API¶

Once you have acquired a new token, you can finally consume the external API by using the token as a Bearer token:

GET /resource HTTP/1.1

Host: api.example.com
Authorization: Bearer eyJraWQ...