Overview of Authentication

This article introduces the use of OpenId Connect for user authentication.

Our APIs use OpenId Connect ([OIDC](http://openid.net/connect/)) flows to authenticate users. This guide refers to OAuth2.0 (commonly shortened to "OAuth"). OAuth is an implementation agnostic description of authentication flows. OpenId Connect is a full implementation of OAuth. The terms and concepts introduced in OAuth and OpenIdConnect are used throughout this document.

Users are authenticated using an OpenIdConnect `token` endpoint. Once a user authenticates, the system uses a internally home-grown system to perform access control checks. Access control checks determine whether or not an authenticated user can call a given endpoint or perform an action on a specific resource. This guide's focus is authentication.

All applications written against the system need to authenticate themselves and their users. Developers writing client applications against the system's APIs pass their users' credentials to the system authorization server in exchange for access tokens. There are many different _flows_ for exchanging credentials for tokens. These flows are covered extensively in the OAuth literature, as well as in this document. See [implementation information](#implementation-information) for helpful links.

The platform supports three flavors of tokens, as described by OIDC. In brief, the platform supports _access_, _refresh_, and _id_ tokens. Access tokens are used to access APIs as a user on behalf of a client application. Typically, access tokens are sent in the `Authorization` header of an HTTP request like `Authorization: Bearer {{ACCESS_TOKEN}}`. Refresh tokens can be used to gain new access tokens from the authorization server. Refresh tokens have long lifespans whereas access tokens have a short lifespan. Requesting an access token using a refresh token is a chance for the authorization server to deny the client a new token if security has been compromised. Finally, identity tokens identify a user and may contain additional pieces of user information like email and name.

For the specifics of gaining access tokens, refer to [the tokens page](tokens.md)

.

Integration Methods

OAuth supports different methods of integrating your application, depending on your security requirements. This section covers the integration methods we currently support.

Clients

The most popular way to access the Platform is using an OAuth client with a _service-account_. On the system, they are commonly referred to as just _clients_. In the OAuth specification, this specific authentication scenario is described as an OAuth Client, which is also a Resource Owner (see, [RFC](https://tools.ietf.org/html/rfc6749#section-4.4)). In this case, the client application has an associated user, called a service-account, who has access to specific objects on the platform. Clients are typically used when two backend systems are communicating with each other. Clients should not be used in environments where secrets can be easily compromised, like the browser.

If you require client-based grants, you need *client credentials*. If you have not been issued client credentials, contact your Autonomic Customer Success representative.

Your credentials carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, or client-side code. For more information on OIDC, consult the OpenID Connect [official documentation](https://connect2id.com/learn/openid-connect).

Common Client Use Cases

  • A backend system needs to run periodic software updates on devices. The application isn't an end user but still needs access to devices and so it is a resource owner.
  • A customer wishes to manage their own users and implement access control on top of the system APIs. In this case, they create their own web backend and give the backend access to the system via a Client. The client receives access to all the system resources of the customer. The client provides all system access, and the system does not know about the customer's end users.

Token Exchange with Mobile Apps

Some trusted partners integrate their applications using Token Exchange, a relatively new OAuth grant type that supports exchange the token of one authorization server for the tokens of another's.

In this scenario, the system learns of the existence of users from the integrating security domain and allows the system to assign permissions directly to these users. This scenario is desirable if the customer wishes to use the ssystem for access control.

Common Token Exchange Use Cases

  • A mobile application is integrating its users with the system so that permissions can be assigned directly to these users.

Authentication Lifecycle

Access Token

The following steps illustrate a typical token session lifecycle:

  1. Call the system's authorization server `token` endpoint, providing your credentials.
  2. If the credentials are valid, a successful response containing at least an access and refresh token.
  3. Call a system API endpoint, providing your access token in the HTTP `Authorization` header like `Authorization: Bearer {{ACCESS_TOKEN}}`.
  4. If the access token is valid and not expired, and you have access permissions to the endpoint, you will receive a valid response back.
  5. When the access token expires, you receive a 401 code from the API. You can gain another access token using the Refresh grant described below.

Refresh Token

  1. For an expired access token, call the authorization server, passing in the refresh token in the body of the request according to the OpenId Connect specification, this is known as the `refresh` grant type in OAuth parlance.
  2. A response is returned containing a new access token and refresh token.

Additional Information

Cross-Origin Resource Sharing

The system supports [cross-origin resource sharing CORS. Browsers generally implement a *same-origin policy* to prevent javascript code from making requests against a different origin (domain) other than the one from which it was served, for security purposes. CORS is a technique for relaxing the same-origin policy, allowing Javascript on a web page to consume a REST API served from a different origin, and in the system, allows you to interact securely with our APIs from your client-side web application.

Protocol Information

The system supports OpenID Connect (OIDC) for authentication. OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. The protocol allows Client applications to call the system's APIs on behalf of the Users who own resources like vehicles, and devices managed by the system.

OpenID Connect considers a variety of client types, each with different security profiles including, web-based javascript, mobile, and secure backend clients. With each client type, it is possible to securely to request and receive information about authenticated sessions and end-users. Both OAuth and OIDC are broadly adopted by companies such as Google, Amazon. Microsoft, IBM, and many others.

Implementation Information

The system's OpenID Connect flows are implemented by an open-source project, Keycloak. In general, the information covered in the system documentation is a subset of the full documentation available from the Keycloak community. Some relevant links to Keycloak documentation are found below.

Link Description
OIDC Endpoints Usage for the Token Endpoint. This endpoint is what enables authenticating users, i.e. exchanging credentials for an Access Token.
Adapters Overview of adapter libraries the Keycloak community has created for integrating with their system.
RFC 6749 Although verbose, the RFC for OAuth2.0 introduces terminology which is invaluable for understanding how Keycloak functions.