File and Object Storage

An Introduction to OAuth 2.0 and OIDC

OAuth 2.0 is a standard which enables client applications access to protected resources hosted by another service on behalf of a user. If you have ever authorized an application to read your email, post to your favorite social media site, etc, you are already familiar with the use cases OAuth 2.0 solves. At a high level, OAuth 2.0 involves the provisioning of an access token which acts as proof that authorization has been granted.

OpenID Connect (OIDC) is a simple identity layer on top of OAuth 2.0. While OAuth 2.0 was focused on handling authorization, OIDC handles authentication. OIDC can be used by client applications that wish to delegate authentication to a 3rd party.  It uses the same flows and concepts from OAuth 2.0 and adds a new token called the identity token.  An identity token is a JSON Web Token (JWT) and is proof of authentication. Access tokens can also be JWTs, but they don’t have to be. This 3rd party is also responsible for safe handling of user credentials and enforcement of authentication policies such as password rotation and multi-factor authentication (MFA). They can also maintain their own authenticated session for users. So, if multiple applications wish to use the same 3rd party, the user does not have to necessarily authenticate multiple times. This is known as Single Sign-on (SSO).

There are 4 major participants. They are:

1. Resource Owner - The entity that can grant access to protected resources. This is typically an end-user.
2. Client Application - The entity requesting access to protected resources on behalf of another user. If the application is delegating authentication and therefore using OIDC, this is also known as the Relying Party (RP).  If you’ve ever used a web application that says “Login with ABC”, it is likely using OIDC.
3. Authorization/Authentication Server - The entity authenticating the resource owner, handling authorization, and providing tokens when necessary. In OIDC terms, this is known as the OpenID Provider (OP).
4. Resource Server - The entity hosting protected resources.

You may be wondering, how does this actually work? There are multiple flows (also called grants) which are just ways to acquire tokens (access or ID) and each one requires a specific set of participants to execute the flow.

Here’s a typical flow:

This is known as the Authorization Code flow and is typically used by server-side applications. Here’s how it works:

1. A user opts to Login to the client application (the server-side application in this flow) with their favorite service or social login. Reminder, this is known as the OP.
2. The client application redirects the end-user’s browser to the OP.
3. The end user authenticates with the OP and authorizes the client application  access any protected resources.
4. The OP redirects the user back to the client application with an authorization code.
5. The client application sends the authorization code back to the OP along with the client application’s credentials. These credentials are typically a client ID and client secret.
6. The OP authenticates the client application using the provided credentials and validates the authentication code.
7. The OP creates an access token and ID token and sends it back to the client application.
8. The client application sends the provided access token to the resource server.
9. The resource server validates the access token and returns the requested resources.

Configuring the IBM Cloud Object Storage Manager™ 

Now that we have a good understanding of OAuth 2.0, OIDC, and the parties involved, let’s take a look at how to configure the IBM Cloud Object Storage Manager™ with an OIDC Provider (OP). 

Once enabled, the first task is to identify the endpoints that are published by your chosen OP. If you know the issuer URL, the IBM Cloud Object Storage Manager™ can find these values automatically. They can always be entered manually and your provider’s documentation should provide them. All of these endpoints must be configured as they are part of the Authorization Code flow and the IBM Cloud Object Storage Manager™ uses this flow when logging into the application. So, the IBM Cloud Object Storage Manager™ is the client application (RP). 

The next set of options describe embedded attribute names and values that the IBM Cloud Object Storage Manager™ should look out for when processing tokens. In a JWT, attributes defined in the token are called claims.

The Group Claim is important for access control. The Group Claim specified here should be the JWT claim name that specifies group membership as defined in your OP. This is typically something like “groupIds” or “groups”. This can be found in your OP’s documentation.

The Audience is a JWT claim value  that identifies the IBM Cloud Object Storage Manager™ as the intended recipient of the JWT. If you intend to use access tokens provided by the OP for IBM Cloud Object Storage Manager™ REST API access, you must specify the same value that is configured for the IBM Cloud Object Storage Manager™ on the OP side. Access tokens that do not contain this value in the Audience claim will be rejected by the  IBM Cloud Object Storage Manager™ REST API.

The ACR is a JWT claim value that represents the Authentication Context. If specified, the IBM Cloud Object Storage Manager™ will validate that all tokens contain an ACR claim with this value. This setting can be used to enforce that a certain policy (e.g. multi-factor authentication) is applied prior to granting the end-user IBM Cloud Object Storage Manager™ access. Please see your OP documentation for details on supported ACR values and what they mean.

The next set of attributes to configure describe how the IBM Cloud Object Storage Manager™ authenticates itself with the OP. There are 4 supported schemes. They are:

• Client secret basic
• Client secret POST
• Client secret JWT
• Private key JWT

The scheme must match what is marked as acceptable by the OP.

The schemes that start with “Client secret” all use the IBM Cloud Object Storage Manager™ configured client ID and client secret on the OP side. Reminder that the client ID and secret are the client application’s credentials and are usually generated by the OP. You should be able to extract these from the OP’s configuration page for the IBM Cloud Object Storage Manager™.

Private key JWT refers to a scheme  that uses the configured RSA private key to digitally sign a JWT produced by the manager that can be used by the OP to identify the IBM Cloud Object Storage Manager™. You must upload the corresponding public key to the OP if using this scheme. Please see your OP documentation for details.