Scopes¶
A scope in Maskinporten terminology is equivalent to a distinct API. As an API provider, you will:
- define scopes to be registered in Maskinporten
- grant access to other organizations for your defined scopes
The notion of scope is loosely defined to allow semantic freedom in terms of API providers' own definition and granularity of access and authorization.
An external consumer that has been granted access to your scopes may then acquire an access_token
with their own Maskinporten client, which they will need to acquire from DigDir on their own.
Our NAIS clients are registered as part of the NAV organization and may only be used by NAV.
Spec¶
See the NAIS manifest.
Configuration¶
spec:
maskinporten:
enabled: true
scopes:
exposes:
- name: "some.scope.read"
enabled: true
product: "arbeid"
allowedIntegrations:
- maskinporten
atMaxAge: 120
consumers:
- orgno: "123456789"
# required for on-premises only
webproxy: true
Scope Naming Format¶
All scopes within Maskinporten are defined using the following syntax:
Prefix¶
The prefix for all scopes provisioned through NAIS will always be nav
.
Subscope¶
A subscope should describe the resource to be exposed as accurately as possible (e.g. trygdeopplysninger
or helseopplysninger
).
The subscope may also be postfixed to separate between access levels, for instance read
and/or write
access (e.g. nav:trygdeopplysninger.write
).
Absence of a postfix should generally be treated as strictly read
access.
All subscopes for NAIS clients will have the following form:
where separator
is:
/
if and only ifname
contains/
.:
otherwise.
Subscope example
For the example configuration above where
product := arbeid
name := some.scope.read
the subscope will be the following:
which results in the scope:
Subscope example with different separator
If the name
instead contains the /
character, e.g:
name := some/scope.read
and the product is the same as before:
product := arbeid
the resulting subscope will be:
which results in the scope:
Audience Restrictions¶
If there are multiple APIs that are protected by the same scope, one might be susceptible to replay attacks.
One way to mitigate this is to require that tokens contain an aud
claim with a unique value for each unique API.
The API should reject requests with tokens that do not have this claim and expected value.
This ensures that an access_token
may only be used for a specific API.
The value of this must be defined by the API provider out-of-band from Maskinporten. It is thus the API provider's responsibility to inform any consumers of this expected value so that they can modify their requests accordingly.
See DigDir's documentation on audience-restricted tokens for more information.
Delegation of scopes¶
Delegation of scopes is not supported in the NAIS-manifest, please see IaC repository for configuration options. This will also require you to configure your scope(s) in the IaC repository to match the delegation configuration.
Legacy¶
Info
This section only applies if you have an existing scope registered at the IaC repository or use the scope in on-prem clusters today.
Application do not use the IaC repo and is migrating from on-prem to gcp¶
The scope is assigned your application in your current cluster;
so when migrating from on-prem nais to gcp, the scope belongs to that cluster. If you already migrated your app, there is no reason to panic, scope still exists and works as before, but you are not able to make changes eg. add/remove consumers until cluster is updated. Right now the cluster need to be changed manually so please take contact in channel #nais.
Migration guide to keep existing Maskinporten scope (IaC -> nais.yml) (NAIS application only)¶
The following describes the steps needed to migrate a scope registered in IaC repository.
Step 1 - Update your scope description in the IaC repository¶
- Ensure the
description
of the scope registered in theIaC
repository follows the naming scheme:
Info
clutser, metadata.namespace and metadata.name containing -
should be joined instead.
subscope
is described her subscope. Describes the scope without the nav:
prefix.
Example: mycluster:mynamespace:myapp.my/scope.read
Step 2 - IaC repository provisioning the scope client to Digdir.¶
- Wait for IaC repo actions to finish. maskinporten IaC actions
Step 3 - Deploy your NAIS application with Maskinporten provisioning enabled.¶
-
Ensure exposed scopes enabled and name matches the already exposed
subscope
-
See configuration.
Step 4 - Delete your scope from the IaC repository¶
- Verify that everything works after the migration
- Delete the scope from the IaC repository in order to maintain a single source of truth.
Created: 2021-08-13