Technologies

OAuth 2

OAuth 2.0 is open standard protocol that is used to provide app authorization.

Open ID Connect (OIDC)

OIDC is an authentication layer that works with OAuth 2. When you use OIDC and App ID together, your application credentials help to configure your OAuth endpoints. If you use the SDK, the endpoint URLs are built automatically. But, you can also build the URLs yourself by using your service credentials. The URL takes the following form: App ID service endpoint + "/oauth/v4" + /tenantID.

Example:

{
  "clientId": "7eba72ef-b913-47b0-b3b6-54358bb69035",
  "tenantId": "8f5aa500-357e-443a-aab6-bf878f852b5a",
  "secret": "OWEzZGM4M2UtZjhlYS00MDI2LTkwNGItNDJmYzViMmU2YzIz",
  "name": "testing",
  "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/8f5aa500-357e-443a-aab6-bf878f852b5a",
  "profilesUrl": "https://us-south.appid.cloud.ibm.com",
  "discoveryEndpoint": "https://us-south.appid.ibm.cloud.com/oauth/v4/8f5aa500-357e-443a-aab6-bf878f852b5a/.well-known/openid-configuration"
}

Using this example, the URL would be https://us-south.appid.cloud.ibm.com/oauth/v4/8f5aa500-357e-443a-aab6-bf878f852b5a. You would then append the endpoint that you wanted to make a request to. Check out the following table to see some example endpoints.

When you use the SDK, the endpoint URLs are built automatically.

Tokens

The service uses three different types of tokens. Tokens are set in the Identity Providers > Manage of the App ID dashboard. For more information about tokens and how they're used in App ID, check out Managing tokens.

• Access tokens: Represent authorization and enable communication with protected backend resources. The resources are protected by authorization filters that are set by App ID.

• Identity tokens: Represent authentication and contain information about the user.

• Refresh tokens: Can be used to obtain a new access token without reauthenticating the user. By using refresh tokens, users can allow their information to be remembered by the application, which means that they can stay signed in.

Authorization headers

App ID complies with the Bearer token specification and uses a combination of access and identity tokens that are sent as an HTTP Authorization header. The Authorization header has three different parts that are separated by white space. The tokens are base64 encoded. The identity token is optional.

Example:

Authorization=Bearer <accessToken> [<idToken>]

API Strategy

The API strategy expects requests to contain an authorization header with a valid access token. The request can also include an identity token, but it is not required. If a token is invalid or expired, the API strategy returns an HTTP 401 error that contains the following HTTP header:

Www-Authenticate=Bearer scope="<scope>" error="<error>"

If the request returns a valid token, control is passed to the next middleware and the appIdAuthorizationContext property is injected into the request object. This property contains original access and identity tokens, and decoded payload information as plain JSON objects.

Web app strategy

When the web app strategy detects unauthorized attempts to access a protected resource, it automatically redirects a user's browser to the authentication page, which can be provided by App ID. After successful authentication, the user is returned to the web app's callback URL. The web app strategy obtains access and identity tokens and stores them in an HTTP session under WebAppStrategy.AUTH_CONTEXT. It is up to the user to decide whether to store access and identity tokens in the app database.

Redirect URIs

App ID uses a list of fully qualified, approved URIs to redirect your users after an interaction with your app. For example, if the user successfully signs in, App ID redirects the user to the home page of your app or to another page that you specify. The format of your URI might change depending on your application. Check out Adding redirect URIs for more information.

JSON Web Key Set (JWKS)

A JWKS represents a set of cryptographic keys. App ID uses a JWKS to verify the authenticity of the tokens that are generated by the service. By using the key ID to verify the signature, we can ensure that the token was issued by a trusted source - App ID. We can also ensure that the information within the token was never changed.