Link

OAuth 2.0 and OpenID connect basics

In all the OAuth 2.0 and OpenID Connect flows, there are four parties involved in the exchange:

OAuth terms Description
Resource owner (End-user) An entity that owns the data and is capable of granting access to a protected resource. When a resource owner is a person, it is referred to as an end-user.
Client (App) An application making protected resource requests on behalf of the resource owner and with its authorization.
Authorization server (apaleo Identity API) The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.
Resource server (apaleo Resource APIs) The server hosting the protected resources, capable of accepting and responding to protected resource requests using access tokens. It trusts the authorization server to authenticate and authorize the OAuth client securely.

Apaleo Identity API endpoints

Endpoint Description
https://identity.apaleo.com/connect/authorize A client app may send a request to this endpoint to receive authorization to access a resource owner’s data residing on a resource server. This action initializes an OAuth flow.
https://identity.apaleo.com/connect/token Post an OAuth 2.0 grant (auth code, refresh token, client credentials) to obtain access and / or ID token.
https://identity.apaleo.com/connect/introspect Validate an access token and retrieve its underlying authorization (for resource servers).
https://identity.apaleo.com/connect/revocation Revokes access or refresh token. This endpoint is only applicable to the authorization code grant flow.
https://identity.apaleo.com/connect/endsession To use the end session endpoint, a client application will redirect the user’s browser to the end session URL.
https://identity.apaleo.com/connect/deviceauthorization Can be used to request device and user codes.

Following endpoints are provided to support OpenID Connect:

Endpoint Description
https://identity.apaleo.com/connect/userinfo Retrieve profile information and other attributes for a logged-in end-user.
https://identity.apaleo.com/connect/checksession Poll the OpenID provider for changes in end-user authentication status.
https://identity.apaleo.com/.well-known/openid-configuration/jwks Retrieve the public server JSON Web Key (JWK) to verify the signature of issued tokens or to encrypt request objects to the server.
https://identity.apaleo.com/.well-known/openid-configuration Discover the OAuth 2.0 / OpenID Connect endpoints, capabilities, supported cryptographic algorithms, and features. It can be used to configure applications.

For more information on OAuth 2.0 endpoints, see RFC 6749 and RFC 7009.


Why use OpenID Connect for my app?

OpenID Connect is easy to integrate, and it can work with a wide variety of apps. Because OpenID Connect is a layer on top of OAuth 2.0, your app can use our APIs for both user authentication and authorization. Your app will use OAuth 2.0 flows to obtain access token plus an ID token. The id token is a JWT and contains information about the authenticated user.

OpenID Connect provides a single protocol for authentication and authorization (OAuth 2.0 access tokens).


Implementing OpenID Connect

There are many OpenID Connect certified libraries for different development platforms. You have to choose the one that suits you best. In our experience, it takes a longer time to write the code yourself than using a pre-written library.

OpenID Connect is a well-documented specification, and we recommend you consult the following resources to assist you with this process. Considering the security implications of getting the implementation right, apaleo encourages you to use a certified OpenID Connect client.


Discovery document

The discovery document (also known as “well-known endpoint”) is a set of OpenID Connect values that can be retrieved by OIDC clients. It enables OIDC clients to automatically configure themselves. The Discovery document for Apaleo’s OpenID Connect service can be retrieved from:

https://identity.apaleo.com/.well-known/openid-configuration

To use apaleo’s OpenID Connect services, you should hard-code the Discovery-document URI (https://identity.apaleo.com/.well-known/openid-configuration) into your application. Your application will fetch the document and retrieve endpoint URIs from it as required. For example, to authenticate a user, your code would retrieve the authorization_endpoint metadata value (https://identity.apaleo.com/connect/authorize) as the base URI for authentication requests that are sent to apaleo.

You can access the discovery document page simply by entering the URL for the well-known endpoint or by using an API call to return discovery document values in JSON format.

For example, here’s a Curl command for returning the discovery document:

curl -XGET -H "Content-type: application/json" 'https://identity.apaleo.com/.well-known/openid-configuration'

Regardless of the method you choose, here’s the sort of information you’ll get back in return:

{
   "issuer":"https://identity.apaleo.com",
   "jwks_uri":"https://identity.apaleo.com/.well-known/openid-configuration/jwks",
   "authorization_endpoint":"https://identity.apaleo.com/connect/authorize",
   "token_endpoint":"https://identity.apaleo.com/connect/token",
   "userinfo_endpoint":"https://identity.apaleo.com/connect/userinfo",
   "end_session_endpoint":"https://identity.apaleo.com/connect/endsession",
   "check_session_iframe":"https://identity.apaleo.com/connect/checksession",
   "revocation_endpoint":"https://identity.apaleo.com/connect/revocation",
   "introspection_endpoint":"https://identity.apaleo.com/connect/introspect",
   "device_authorization_endpoint":"https://identity.apaleo.com/connect/deviceauthorization",
   "frontchannel_logout_supported":true,
   "frontchannel_logout_session_supported":true,
   "backchannel_logout_supported":true,
   "backchannel_logout_session_supported":true,
   "scopes_supported":[
      "openid",
      "profile",
      "transactional-data.delete",
      "reservations.import",
      ....................
      "offline_access"
   ],
      ...............
}

Which OAuth 2.0 grant works best for me?

A grant is a method to acquire an access token. To decide the implementation of a grant, you need to consider the type of client end-user will be using and the end-user experience.

OpenID Connect supports the following authentication flows:

Use Case Trustworthiness Suggested OAuth 2.0 Authorization Grant_type
Publicly available apps (apaleo store apps) - Most secure grant type.
- If the client is a web app that has a server-side component, then you should implement the authorization code grant.
- If you can use server-side scripting, then use this grant.
Authorization code grant
Private apps (custom project for one hotel) - Highly trusted applications, written by internal developers or developers with a trusted business relationship with the user.
- All parties trust each other and no external resources are involved.
- Usually used for machine-to-machine authorization.
- Applications that need to access resources on their own behalf.
Client credentials grant

Implementing OAuth in your applications

The following topics describe how to generate OAuth access tokens using each of the two grant flows: