Managing Applications

Organizational applications represents customer applications that need to authenticate on their own behalf to perform actions using Naviga Content tools and APIs. Common use cases are machine to machine operations such as import or export of content to and from CCA and OC.

Organizational applications identify themselves using client credentials, which consists of client_id and client_secret, comparable to username and password. The client credentials are used to fetch an access token, which in turn is used for authentication when accessing Naviga Content tools and APIs. Both client credentials and access tokens are part of the OAuth2 specification.

This page describes how to create and manage organizational applications and related credentials in Naviga ID. For instructions on how to actually use client credentials to fetch access tokens and access APIs, see Fetching and using Access Tokens.

Creating an application

As of December 2021, the Admin App that is used to manage Naviga ID configuration does not yet support managing applications and client credentials. However, the Admin API does support all required operations.

The full API for managing applications and credentials are available at the Admin API page.

To create applications, the role imid:admin is required. Auth can be either an ID-Token or Access-Token, either as cookie or in the Authorization HTTP header as Bearer token.

To create an application, you'll need the organization id, not the name. The organization id can be seen in the URL when configuring an organization in the Admin App at https://admin.stage.imid.infomaker.io

There are two ways to define the permissions an application should have. The legacy way by using groups, and the recommended way of using scopes.

Specifying permissions using scopes

Scopes are simply string representations of roles and permissions that includes information if the role or permission is valid in a specific unit or the entire organization.

By using scopes to define what an application is allowed to do, all "group-to-role" mappings in Naviga ID are bypassed. So instead of using an intermediate format and config, the roles and permission that an application are allowed to assume is defined directly in the application itself on creation (can be updated).

Another benefit with scopes is that they are also used when fetching access tokens. This enables fetching of tokens with a subset of the permissions an application is allowed to assume which greatly limits the implications if an access-token would be shared or leaked. To learn more about this, go to the how to fetch access-tokens page.

All scopes have the following format

["permission"|"role"]:[unitName|"*"]:[serviceName]:[entityName]

Below are example of the allowed type of scopes when creating applications

Example scope	Description
permission:gl-news:opencontent:view	Will give the application the opencontent:view permission only in the gl-news unit
permission:*:opencontent:view	Will give the application the opencontent:view permission in all units in the org
role:gl-news:opencontent:readOnly	Will give the application all permissions in the opencontet:readOnly role only in the gl-news unit.
role:*:opencontent:readOnly	Will give the application all permissions in the opencontet:readOnly role in all units in the og.

To use multiple scopes, simply create a space separated list of them as the example below.

permission:gl-news:opencontent:view permission:gl-news:opencontent:write

To create an application, you'll need the organization Id, the name you want to give the application, a description as well as the scopes that you wish to give the application.

To create an application, use the /v1/organizationApplications.create in the Admin API. The scopes that define roles and permissions that the applicatin can assume should be entered in the allowedScopes payload parameter. See the documentation for a full description.

In the response you'll get the id of the application (client_id) as well as one initialclient_secret that you'll need to fetch an access-token. To enable easy rotation of secrets, Naviga ID supports multiple client_secret per application. For more details, see the section about rotation of credentials lower down on this page.

Specifying permissions using groups

This method is no longer recommended. Instead, please use scopes as described in the step. With scopes, the application owns the configuration and can also fetch access-tokens that only hold a subset of permissions that an application is allowed to take.

To create an application with permissions based on groups, you'll first need the organization Id, the name you want to give the application, a description as well as the groups that you wish the application to belong to. The groups you define will be used to map roles/units according to the organization's configuration in Admin App.

To create an application, use the /v1/organizationApplications.create in the Admin API. See the documentation for a full description.

In the response you'll get the id of the application (client_id) as well as one initialclient_secret that you'll need to fetch an access-token. Naviga ID supports multiple client_secret per application, to enable easy rotation of secrets. For more details, see the section about rotation of credentials lower down on this page..

Rotation of credentials (client_secret)

Credentials can, and should be rotated in defined intervals for security reasons.

To enable easy rotation of client_secret, Naviga ID Organizational Applications support multiple credentials. That way, it's possible to rotate credential with zero downtime in services by creating a new credential for the application and updating all places where the old credential is used before removing it from Naviga ID.

See the Admin API documentation on Organization Applications for details on how to find the id of the current credential, create a new credential and delete the old credential.

Use client credentials to access Naviga Services

See Fetching and using Access Tokens.