All calls to the backend API:s require the user to be authenticated. Clients authenticate using the OAuth 2 Authorization Framework and the OpenID Connect Authentication protocol which is built upon it. The authentication process is handled by IFS Platform and the configured Identity Provider(s). A part of the IFS Platform called the IFS Identity and Access Manager (IFS IAM) handles the authentication. This component is an OAuth2 authorization server which produces access tokens that can be used to access the backend API:s. It supports multiple OAuth2 flows which allow for different clients to authenticate in the manner which is appropriate to them. It can also be configured to handle a multitude of integration scenarios where a third-party app needs to get access.
Out of the box, the IAM maintains its own user registry which is kept in synchronization with the IFS user registry in the database. This user registry is used when authenticating users directly with the IFS IAM which is the default mode for IFS Cloud. In addition, external identity services can be used by configuring the IAM to delegate its authentication. This allows services such as Azure Active Directory to provide single sign on as well as a familiar login experience to the users.
In scenarios where external identity services are used, the IFS IAM will delegate authentication using OpenID Connect to verify the identity of users through external services that implement the OpenID Connect specification. In these cases, the IFS IAM exchanges the external ID tokens from these services for its own access tokens during authentication. The backend API:s only validate the access tokens from the IFS IAM and the users are treated the same way whether or not they are internal to the IFS IAM user registry or delegated to an external party. This means the same endpoints can be used no matter which service was used used to authenticate the user.
More information about the IAM container can be found here.
OAuth2 and OpenID Connect standards
The authentication is based on open standards to ensure the use of designs with well-known security characteristics. In order to learn more of the standards used, the following specifications provide a more detailed and in-depth explanation of the concepts:
- The specification of the OAuth2 protocol.
- The OpenID Connect specification.
- The Bearer Token Usage specification (on how to provide access tokens to the backend from clients).
- The OpenID Connect Discovery specification (on the format of the metadata document served by the IFS IAM to allow clients to communicate with it successfully).
- The Proof Key for Code Exchange (PKCE) specification (on how to secure OAuth2 public clients such as native apps).
Architecture and design
Requests heading into the system are checked for a valid access token from the IFS IAM on the IFS Proxy where all requests pass through in order to get access to the containers serving the IFS backend API:s. If the request lacks a valid access token from the IFS IAM there are two different ways for this to be handled. Browser requests can be redirected to the IFS IAM login page from the IFS Proxy, but many other clients do not respond to redirections and need to instead supply their own access tokens through other means. Both these ways of handling the authentication are possible.
No matter what way is used, the end result is an API request with an attached access token which the backend container can validate. Behind the IFS Proxy, all the authenticated HTTP requests appear the same and authentication is stateless.
Redirection from the IFS Proxy
If the request looks like it comes from a web browser, the IFS Proxy will attempt to redirect the browser to the IAM and use Authorization Code Flow to retrieve an access token. The IFS Proxy creates the proper parameters for the Authorization Endpoint of the IFS IAM to process this request and redirects the browser there. This will cause the IFS IAM to process authentication in the way it is configured to. If it is set up to delegate authentication to an external party it will do this and process the result before sending the user back to the proxy with a one-use code that can be redeemed for an access token. The proxy will then contact a separate endpoint on the IFS IAM called the Token Endpoint to redeem the code for an access token. In order to do this, the proxy must supply a client ID and a client secret which serves as its own credentials to the token endpoint. Upon successful authentication, the IFS Proxy will associate the access token with a session cookie sent back to the browser, and attach this access token to all requests reaching the backend API:s.
In this case, authentication is dependent on a stateful session up until it is past the IFS proxy. Behind the proxy it is stateless and the tokens can be freely consumed by any backend container irrespective of the session cookie.
This flow is illustrated below.
Bearer token usage
For clients that do not respond to HTTP redirects (non-browser applications) there are ways to authenticate using a client-provided access token. In this case, the client needs to communicate with the IFS IAM directly to get ahold of an access token and send this token up as a bearer token. Exactly how this is done depends on the client.
A client with support for graphical OAuth2 flows would use Authorization Code Flow and start a browser controller to render the IFS IAM login page, after which it intercepts the response and redeems the code for a token. This process is very similar to the process described above for browser apps but the entire OAuth2 process happens within the client app rather than on the IFS Proxy. The client app renders the login page at the authorization endpoint, intercepts the code and sends it up to the token endpoint. Because this flow doesn't use a client secret, it is likely to also implement the Proof Key for Code Exchange specification, which the proxy doesn't need because of the use of a client secret.
This flow is illustrated below.
For clients that can not render a browser control, so called direct access grants allow for non-graphical clients to also obtain access tokens. There are two variants of direct grants which can be used depending on the use case, these being Client Credentials Flow and Resource Owner Password Credentials Flow. What sets them apart is their relation to the user credentials. In Client Credentials Flow, the registered client itself is the user and a special service user is attached to the token which is used to represent the needs of the client. This is beneficial to cater for scenarios such as kiosk apps and automated scripts. If an end-user account is needed for a non-graphical client for some reason, the Resource Owner Password Credentials flow can be used for this. In this case the username and password of the desired end user must also be provided.
Both these flows are very similar and follow the process illustrated below.
If a bearer token is provided, the proxy will not attempt to perform an HTTP redirection but will rather do some basic validation and send the request through to the backend API:s. In this case, authentication is fully stateless including on the outside of the IFS Proxy.
NOTE: If it is possible for a client to use Authorization Code Flow, this is always recommended over the use of direct access grants due to being more user-friendly and feature-complete. If direct access grants are used, use of Client Credentials Flow is recommended over the use of Resource Owner Password Credentials Flow whenever possible. Use of Resource Owner Password Credentials flow with a user associated with an external identity provider is not supported which means that for this flow to work the users need to be handled by the IFS IAM user registry.
Basic authentication as a last resort
If there is a necessary integration that can not do any of this, the last option is for a client to use HTTP Basic authentication in order to access the system. This is not recommended and has to be specifically enabled on the IFS Proxy, but if there is no other way to service a particular integration then it is available as an option.
The behavior that is triggered here is for the IFS Proxy to extract the username and password from the Basic authorization header and use Resource Owner Password Credentials Flow to exchange these for a token. This mimics the behavior of consuming a Basic authorization header but makes sure that there is still an access token available to the backend as expected.
NOTE: If it is possible for a client to use Authorization Code Flow or any of the direct access grants, this is always recommended over the use of HTTP Basic grants. Use of Resource Owner Password Credentials flow with a user associated with an external identity provider is not supported which means that for this flow to work the users need to be handled by the IFS IAM user registry.