Skip to content

Direct access grants

Direct access grants allow for non-interactive authentication. This is useful for such use cases as server-to-server authentication, authenticating using automated scripts, kiosk applications and some legacy integrations. This section describes how to set up or implement Client Credentials Flow or Resource Owner Password Credentials Flow for integration purposes.

Authentication using Client Credentials Flow

While Authorization Code Flow is the best flow to use for integrating graphical end-user applications, some applications come with different requirements. Applications that are incapable of rendering a browser can use other flows, and some applications do not need end user accounts in order to access the system to do some limited tasks. For these applications, Client Credentials flow allows for a non-interactive authentication of a service account where the authorization endpoint is never contacted and the request is done non-interactively directly to the token endpoint using pre-configured credentials. This form of authentication yields an access token associated with a service user that is associated with the OAuth2 client itself rather than an end user account. The client ID and client secret of a client registration set up to allow this flow acts as the username and password for the integrating application.

Use-case, advantages and limitations of Client Credentials Flow

There are a few cases where this form of authentication is more beneficial for integration purposes. The first case is for server-to-server integrations where there is no graphical client involved in authentication and as such no end user logging in. This can be a non-interactive background process running on an integrating server or something of that sort. Third-party servers can also use this to authenticate and do some limited tasks that result from end-user input on their side, but the authentication for IFS Cloud will be associated with the integration itself rather than with the end user. Such a design requires the appropriate security checks to be made by this third-party product before the request is made since the permissions granted in IFS Cloud will be associated with the integration itself which is likely allowed to do everything this integration has been set up to be able to do.

Another common use case is kiosk applications. These are graphical applications that are running on terminals in the work place that those interacting with the terminals can use without end user authentication. Their purpose may be to display information, or they may also modify data. These applications use client credentials to authenticate towards IFS Cloud with an access token associating them with the application or terminal itself. These clients can use some other method of identifying the user, but their requests to IFS Cloud will have the permissions associated with the terminal itself. This means that any security checks should be made by the application itself using some other method.

This flow enables applications to integrate in a non-interactive way, but the main limitation is that the access token generated is associated with the application itself and not with any end user of IFS cloud.

How to configure client registrations for Client Credentials Flow

In order to set up a client registration to be able to use client credentials flow, the following must be true:

  • The client registration must be a confidential client so that a client secret exists.
  • The client must be set up to allow direct access grants. This enables all the flows that bypass the authorization endpoint.
  • The client must be set up to have service accounts enabled and a service account associated with it. This enables Client Credentials Flow.

Below is a picture of such a client being set up in Solution Manager.

A client setup for the IFS IAM for use with Client Credentials Flow.

How to perform Client Credentials Flow

When performing client credentials flow, only the token endpoint is ever contacted. The way this is done is by sending an HTTP POST request much like is done in the code exchange step of Authorization Code flow, but with slightly different parameters. The following parameters are used to perform a token request using Client Credentials Flow:

  • grant_type: Should always be "client_credentials" denoting the use of Client Credentials Flow.
  • client_id: Should be the client ID of the client registration made for the IFS IAM in Solution Manager.
  • client_secret: Should be the client secret of the client registration made for the IFS IAM in Solution Manager.
  • scope: Use the same scopes as you would for Authorization Code Flow in the request to the authorization endpoint. See more here.

The response provided from the token endpoint will look very similar to the token response in Authorization Code Flow, described in this section. Once the access token has been extracted, it can be used as a bearer token also in the same manner as with Authorization Code Flow. In order to find the token endpoint, a call to the discovery endpoint can also be made in the same manner as described here.

Example in Postman

Below is an example of a Client Credentials Flow token request, made in Postman:

Client Credentials Flow token request set up in Postman.

Authentication using Resource Owner Password Credentials (ROPC) Flow

There are some instances where an integration needs to perform an authentication without rendering a browser dialog but still get an access token associated with the identity of an end user. In these cases, Resource Owner Password Credentials Flow (ROPC) offers a way to do this.

Use-case, advantages and limitations of ROPC

This is mostly intended for use with legacy applications where a plugin can be written to handle fetching an end user token using ROPC. Use of ROPC is generally discouraged and this should only be used in case none of the other flows work. ROPC goes against one of the main philosophies of OAuth2 and modern federated authentication because it requires OAuth2 clients to handle end user credentials. This is viewed as disadvantageous because the OAuth2 protocol usually allows for the user to authenticate using any method configured, but with ROPC it needs to be possible with only user credentials that are validated by the IFS IAM.

This restricts what types of users can use this quite a bit. The OAuth2 clients use the username and password of the user to request a token from the IAM, which means that for this process to work the IAM must be able to validate this password. This is only possible in the case of a user that is native to the IFS IAM. Users that log in through external identity providers will not be able to easily use this flow. Even if external users could use the flow, the use of ROPC makes it impossible to configure multi-factor authentication for these users.

Use of this flow should therefore be limited as much as possible. If no external identity providers are used it may not be much of a problem, but getting this ingrained in the business flows will hamper the ability to use external identity providers in the future. It may also prevent the use of any future feature for the IFS IAM that would authenticate users in any other way than simple credentials consisting of username and password.

Opting to integrate using ROPC rather than Authorization Code Flow for reasons of simplicity is discouraged.

Despite these disadvantages, availability of ROPC is maintained for those select integrations that need it.

How to configure client registrations for ROPC

Setup of a client registration for use with ROPC is very similar to doing the same for Client Credentials Flow. The main difference is that service account configuration is missing for client registrations that are designed to do ROPC.

  • The client must be set up to allow direct access grants. This enables all the flows that bypass the authorization endpoint.
  • The client registration can be either public or confidential. If made confidential it will require the client secret in order to return an access token through ROPC. The decision to make this client registration public or confidential hinges on whether the OAuth2 client is structured in such a way that it can securely keep a client secret. If the entity doing the post request resides serverside then it can securely keep a client secret and should always opt to use a confidential client. If this is not possible, such as in the case of the flow being performed by a native app on the end user's device, use a public client.

The below image illustrates setting up a client registration to do ROPC using Solution Manager. In this case, a public client registration has been used.

Client Credentials Flow token request set up in Postman.

NOTE: Since the setting that enables ROPC is the enabling direct access grants, this means that clients registered for the use with Client Credentials Flow can also theoretically be used to do ROPC. In practice this is rarely the case because these clients are always confidential and their secrets are only kept by the devices that do Client Credentials Flow.

How to perform ROPC

Just like with Client Credentials flow only the token endpoint is contacted when getting an access token using ROPC. The parameters are similar but slightly different.

  • grant_type: Should always be "password" denoting the use of ROPC.
  • client_id: Should be the client ID of the client registration made for the IFS IAM in Solution Manager.
  • client_secret: Should be the client secret of the client registration made for the IFS IAM in Solution Manager. If a public client is used, this can be omitted.
  • scope: Use the same scopes as you would for Authorization Code Flow in the request to the authorization endpoint. See more here.
  • username: The username of the end user which is to be associated with the access token.
  • password: The password of the end user which is to be associated with the access token.

The response provided from the token endpoint will look very similar to the token response in Authorization Code Flow, described in this section. Once the access token has been extracted, it can be used as a bearer token also in the same manner as with Authorization Code Flow. In order to find the token endpoint, a call to the discovery endpoint can also be made in the same manner as described here.

Example in Postman

Below is an example of a token request using ROPC, made in Postman:

Client Credentials Flow token request set up in Postman.

Basic authentication leveraging ROPC in the IFS Proxy

For cases where even ROPC does not work there is a way to enable the IFS Proxy to accept a Basic Authorization header. What this actually does, if enabled, is cause the IFS Proxy to perform ROPC using the credentials sent in order to retrieve an access token and associate it with the HTTP request on the way into the namespace. Even though use of ROPC is generally discouraged, using ROPC through Basic Authentication in this way is even more discouraged.

This is optionally available to enable in environments for cases where some integration that can not be replaced will not allow for any other form of authentication to happen than HTTP Basic. It is disabled by default and the recommendation is for it to remain disabled unless it's needed for a good reason.