OpenID Connect - OAuth2

From Cyclos4 Wiki
Jump to: navigation, search

Available from Cyclos version 4.13

Introduction

OAuth2 is an industry standard for a user of a service authorize a third-party service to access its protected information / resources without sharing his credentials with the third-party service. From version 4.13 Cyclos can act as an OpenID Connect / OAuth2 provider. When implemented, third party software can allow users to login in their system with Cyclos credentials.

The flow is normally like this:

  1. The user navigates to the third-party website, which needs his profile data in the original service
  2. The third-party service contacts the original service, requesting access to a specific set of permissions
  3. The original service displays a consent page, where are informed of exactly what will be shared to / accessible by the third-party service, and the user authenticates himself and approves the request
  4. The user is redirected back to the third-party service, in which redirect the original service passes access information
  5. The third-party service calls web services in the original service using that access information

Note: Cyclos in it's turn can also allow users to use external identification providers to login (for example Facebook and Google), this is explained in this wiki page.


OAuth2 is only concerned with authorization. There’s no standard way for the third-party server to know who the user is (authentication). That’s the role of OpenID Connect. It is built over OAuth2 and adds standard ways to access the user profile information. As such, systems that allow a user to login with some other service (Google, Facebook, Twitter,...) implement OpenID Connect, as the only data the third party server needs is the user name, login name, e-mail - all of which are available as standard data in OpenID Connect.


OAuth2 defines 2 authorization flows, started with a request to /authorize:

  • Authorization code flow: The authentication request returns an authorization code. The third party is known in the service provider via a client id and client secret. Those information are passed in to the /token endpoint, together with the authorization code. As a result, an access token is returned. That access token can later be used to call web-services in the original service. To use it, the authorization request parameter must be response_type=code.
  • Implicit flow: The authentication request returns the access token directly. This is more suitable for single page applications which cannot hold the client secret (it should be securely stored in the server, not in client-side code). To use it, the authorization request parameter must be response_type=token.


Besides these, OpenID Connect still defines another concept: the id token. The id token is a JSON Web Token which contains basic information about the user, such as name, login name and e-mail. It is signed by the server (called OpenID Provider - OP), so the third-party service (Relying Party - RP) can check that the data hasn’t been tempered with.

When performing a request, besides the 2 authorization flows defined in OAuth2, OpenID Connect also defines a third one: the Hybrid flow. RP’s are allowed to use the parameter response_type with any combination of code, token and id_token. So, for example, an application that just needs to login with the provider can just request the id_token.

Additionally to the /authorize and /token endpoints defined by OAuth, OpenID Connect defines the /userinfo endpoint. Using the access token, clients can use it to get additional details about the authenticated user.

The permissions are called scopes. When the client performs the authorization request, it passes in the scopes that will be required. When the user sees the consent page, it displays clearly what is being consented. OpenID Connect defines a set of scopes:

  • openid: If requested will run the OpenID Connect protocol. If not, will be plain OAuth2
  • profile: Allows the third-party service to read basic profile information, such as the user name, locale and login name
  • email: Grants access to the user e-mail
  • phone: Grants access to the user phone number
  • address: Grants access to the user address
  • offline_access: A special scope which will enable refresh tokens. These are tokens that can be used to obtain new access tokens after they expire, effectively granting long-term # access to the third-party service to the user data.

Features supported in Cyclos

Cyclos 4.13 supports the OpenID Connect core operations, except for a few parameters. The OpenID Connect discovery well-known/openid-configuration endpoint is supported. Cyclos also supports OAuth2 usage for third-party services to call the REST API in behalf of users for the following operations:

  • View full profile
  • Modify profile
  • View current account status
  • View account history
  • Perform payments / single specific payment per consent

Consent page
The consent page in Cyclos is modelled in a single page for login and consent. Some providers, like Google, have 2 different pages: first login, then consent. For theses services it is beneficial that the user logs in and stays logged-in for a long period of time. It is, for example, highly likely that some user is already logged-in, so they just need to consent. Cyclos, on the other hand, is a financial software. Users should be logged-in for the shortest time possible, to minimize the risk of data theft. So, the consent page presents, in one go, the following:

  • Information about the client performing the request
  • A login form
  • Information about what is being requested
  • The time period the consent will be valid. Iif the offline_access scope is requested, will be until manually canceled, otherwise, there’s a time period defined in the client in Cyclos.

The consent page automatically reads the theme colors from the applied theme in Cyclos. As such, there’s no need for an additional theme type.

All kinds of users can grant a consent: members, brokers, operators and administrators, as long as they can access the web services channel, and it has the OpenID Connect / OAuth2 identification method

Configuring Cyclos

Permissions and basic configuration

Grant permissions for admins to manage the OpenID Connect / OAuth2 clients. Then, in the user’s channel configuration, enable the “OpenID Connect / OAuth2” channel.

Client registration

The first step is to register an OpenID Connect / OAuth2 Client in the User > OpenID Connect / OAuth2 > Clients. It needs a name, client id, client secret, the allowed redirect URLs and the set of permissions the client will be able to request.

The Redirect URL is obtained in the third-party software. The client id and client secret needs to be configured in the third party software.

Access to the granted authorizations

If clients can use the offline_access scope, or if the access token expiration is large, it is important that users can revoke consent granted to the applications. For that, there’s a permission in any kind of product to enable “Search OpenID Connect / OAuth2 authorizations”. It will be accessible in the Personal menu. Managers (admins / brokers) also have view / manage permissions over “User OpenID Connect / OAuth2 authorizations”. They will both be able to search an overview of authorizations and see the authorizations for a specific user from a profile action.

Returning information from custom fields

The information returned from the /userinfo endpoint when the client has the profile scope granted can include custom fields. There is a list of standard information defined in OpenID Connect. Some of these maps to custom fields. For returning them, go to the user custom field definition and set the “OpenID Connect claim value” field to some name. That name will return the field value. A special case to handle is the gender field. It is defined with the values “male” and “female”. For them to be correctly returned, set the corresponding internal names in the possible values.

Access account information

The client can have permission to access the current account status and / or the full account history. For that, grant the corresponding permissions in the client form. Also set the account types the client can access.

Then, from the client, include the account_status and / or account_history in the scope parameter. On the consent page, the user will see that the client wants the account information. Finally, call the corresponding methods in the REST api passing the “Authorization: Bearer ACCESS_TOKEN” header.

Performing payments

The client can have the permission to only perform a specific payment, in which the consent page already shows the payment amount and destination, or to perform any number of payments.

Anyhow, the payment type needs to have the “OpenID Connect / OAuth2” channel enabled. Then use the regular REST payment paths passing in the “Authorization: Bearer ACCESS_TOKEN” header.

Third-party service configuration

If the third party service will be configured to “Login with Cyclos”, probably all it needs is the id_token. If it supports specifying the location of the openid configuration endpoint, set it to: <cyclos-root>/.well-known/openid-configuration. It will then automatically detect the provider capabilities and configure itself accordingly. If not, the endpoints are:

  • <cyclos-root>/api/oidc/authorize
  • <cyclos-root>/api/oidc/token
  • <cyclos-root>/api/oidc/userinfo

Testing the Cyclos configuration

A good tool to test OpenID Connect is https://oidcdebugger.com/. To use it, create a client in Cyclos, set a client id (example: test) and a client secret will be generated. Also set the redirect url to https://oidcdebugger.com/debug.

Then, in https://oidcdebugger.com, copy the client id and secret. Also, set the authorize URI to <cyclos-root>/api/oidc/authorize, and set the scopes as a space-separated list of scope names. For example: openid profile email phone.

The response type can be set to any of the desirable. On continue, the Cyclos consent page will be shown. After granting, oidcdebugger will show all the returned variables. In case an id_token is requested, it will be decoded, and its data will be displayed.

Be aware you can browse to the page: <cyclos-root>/.well-known/openid-configuration to see the supported configuration options. An example can be seen here: https://test.cyclos.org/.well-known/openid-configuration