Getting started with authentication
Requirements
-
Your solution has been registered in Multitenant Access Control and you have received client ID and client secret.
-
You have a public or confidential client set-up and corresponding URLs configured in the application registration process.
See the previous chapter on how to do this set-up.
Authentication in service-to-service communication
A token is required to call another application’s API via service-to-service communication.
Use the Client Credentials Flow with your client’s ID and secret to get this token. A token is valid for one server and one module only. To call the APIs of other modules (resource servers), separate tokens for each module have to be requested via target audience specific scopes. See How to get and handle tokens for more information.
Additional considerations
Your application will likely need certain privileges to call an API of another service. The required roles/privileges have to be assigned to your application in the respective organization. Consult the User Manual for more info on how this is done in the admin UI or the Operations Manual if done programmatically.
Consider that these privileges may not initially or never be granted to your application. Therefore, it is important to provide guidance to users or operators and reattempt service-to-service communication later if it failed due to missing privileges.
Authentication in user-to-service communication
User login in a web application executing on the server (aka from the backend)
This approach requires a backend to be involved. It typically makes use of cookies or server-side sessions.
Use the Authorization Code Grant Flow in your backend implementation to get an authorization code for the current user and exchange it at the OAuth 2.0 token endpoint to a token using the confidential client’s credentials. The token can then be stored in the server-side session or in a cookie. The browser will add the cookies to all requests to the backend automatically. This makes file downloads and websocket connection easier, but requires proper CSRF/XSRF protection.
User login in single-page application, native or mobile app (aka from the frontend)
This approach can be applied to typical pure client side frontends developed with Angular, React or alike. It makes use of the browser’s session storage or a service worker as a more advanced approach.
Use the Authorization Code Flow with PKCE to get a token for the current user without requiring interaction with a backend. This flow does not require a client secret, it just uses the public client’s clientId and properly configured redirect URLs. PKCE will safeguard the authorization code to token exchange. The login can be done using redirects or a pop-up. The token can then be stored in the browser’s session storage. For API calls, just add it to the authorization header with the Bearer prefix.
This approach is similar to the previous one but in this case the exchange of the authentication code to a token is done by PKCE in the browser while in the previous case it was done with the confidential client in the backend without PKCE.
Comparison of authorization code grant flows
| With PKCE | Without PKCE | |
|---|---|---|
Advantage |
|
|
Disadvantage |
|
|
Further considerations
Log-In
-
Autologin: User should be logged in automatically, if there is an active SSO (single sign-on) session for the selected organization.
-
Refresh: Token should be refreshed automatically, if refresh token exists. Otherwise, silent-renew may be usable.
-
Context: User’s context should be preserved. This can either be achieved using a popup for the login or by preserving the current state during the login redirection. Redirection makes sense as a fallback mechanism in case popups are blocked.
Log-Out
There are two types of log out:
-
Log out from application by dropping session and related data. It must be clear for the user, though, that they are just logged out of the current application for the moment, while the SSO session remains active.
-
Log out at authorization server / identity provider to terminate single sign-on session (Single Sign-Out). These functionalities are covered by the OpenID Connect logout specifications:
Authentication methods out of scope
Username + Password
|
Implicit Grant Authorization Flow is insecure and deprecated. It has been used before PKCE was invented, but now that there is PKCE, use Authorization Code Flow with PKCE instead! |
Custom login form with handling of user credentials
The Resource Owner Password Credentials Flow exists for that case. But that also means that the application is responsible for handling the user’s credentials securely. Furthermore, users are desensitized to enter their credentials in other places besides the trusted identity provider increasing the risk for successful phishing attacks. Therefore, this flow is typically not used.
This flow is typically used as a first step to migrate from HTTP Basic Auth to OAuth 2.0.
Further Reading
-
Best Current Practice (Draft) OAuth 2.0 Browser-Based Apps https://oauth.net/2/browser-based-apps/
-
Best Current Practice OAuth 2.0 Native Apps https://tools.ietf.org/html/rfc8252