Version 2.2
1 Introduction
1.1 Scope
The purpose of this document is to provide a high-level overview of how a Governmental web portals (Client) can integrate with CY Login, for user authentication and Single Sign On. The selected protocol is OpenID Connect 1.0 [2].
It is not the purpose of the document to provide a complete implementation guide of how the protocol must be applied by Governmental web portals. It is the responsibility of the integrator to comply with it.
1.2 Target Audience
The intended audience for this document is:
- Software Designers
- Software Developers
1.3 Structure of this document
The document is organized as follows:
- Chapter 1 – Introduction presents the scope and the terminology used in the document
- Chapter 2 – An overview of the design and specifications of the CY Login
- Appendix A – Describes the available Flows of OpenID Connect supported by CY Login
1.4 Interpretation of Requirement Levels
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
document are to be interpreted as described in RFC 2119 [1].
1.5 References
- RFC 2119 – https://www.ietf.org/rfc/rfc2119.txt
- OpenID Connect 1.0 – https://openid.net/specs/openid-connect-core-1_0.html
- PKCE (Proof Key for Code Exchange) – https://tools.ietf.org/html/rfc7636
- OpenID Connect Discovery 1.0 – https://openid.net/specs/openid-connect- discovery-1_0.html
- OpenID Connect RP-Initiated Logout 1.0 – https://openid.net/specs/openid- connect-rpinitiated-1_0.html
- OpenID Connect Front-Channel Logout 1.0 – https://openid.net/specs/openid- connect-frontchannel-1_0.html
1.6 Terms and Definitions
Access Token: The Access Tokens are used in token-based authentication to allow an application to access an API.
Identity Broker: An Identity Broker is often part of a Single Sign-On Architecture as an intermediary service that connects multiple Relying Parties with different Identity Provider (IDP)s. An Identity Broker maps Identity Attributes, including unique identifiers, across multiple Identity Provider (IDP) to one user entity.
Id Token: The ID Token is a security token that contains Claims about the Authentication of an End-User by an Identity Provider, and potentially other requested Claims. The ID Token is represented as a Json Web Token (JWT).
Json Web Token: JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.
OpenID Provider: OAuth 2.0 Authorization Server that is capable of Authenticating the End-User and providing Claims to a Relying Party about the Authentication event and the End-User.
Refresh Token: The Refresh Token is a long-lived token that is used to obtain a new Access Token after a previous one has expired.
Relying Party: Web Application or Mobile/Native Applications or Single Page Applications that relies on the Identity Provider in order to authenticate users and request claims.
Single Sign On: Single sign-on (SSO) is an authentication process that allows a user to access multiple applications by logging in only once with one set of login credentials. With SSO, the application or website that the user is trying to access relies on a trusted third party to verify that users are who they say they are.
1.7 Abbreviations
| FQDN: | A fully qualified domain name |
| IdP: | Identity Provider |
| OP: | OpenID Connect Provider |
| OIDC: | OpenID Connect |
| PKCE: | Proof Key for Code Exchange |
| RP: | Relying Party |
| SSO: | Single Sign On |
| TLS: | Transport Layer Security |
2 CY Login
CY Login building block provides Single Sign-On capabilities acting as an Identity Broker and an Identity Provider for the Public Sector.
2.1 Supported User types
CY Login manages the following user types:
- Citizens that have Cyprus ID or Arc issued by Civil Registry and Migration Department.
- Organizations that are registered in Department of registrar of Companies and Official Receiver.
- EU Citizens through eIDAS network.
2.2 Supported Identity Providers
CY Login currently supports the following Identity Providers:
- Local Provider using Username and Password
- eIDAS cross border authentication for EU Citizens
- Cyprus eID providers (Currently JCC is the sole Cyprus eID provider)
2.3 Technical Information
2.3.1 Configuration Information
CY Login supports OpenID Connect Discovery 1.0 [4].
The configuration information is available at the following locations:
- Production Environment: https://cge.cyprus.gov.cy/cylogin/core/.well- known/openid-configuration
- Test Environment: https://test.cyprus.gov.cy/cylogin/core/.well-known/openid- configuration
2.3.2 Available Scopes
CY Login supports the following mandatory identity scopes:
- openid
- cegg_profile
CY Login supports the following api scopes:
- signature.create
- This scope is requested when the application wants to retrieve an access token to call CY Sign for creating qualified signatures.
- It is only valid when the user logins with Cyprus eID.
Refresh tokens are requested with the offline_access scope.
2.3.3 Available Claims
CY Login returns the following claims for Cypriot natural or legal persons:
| Claim | Description |
|---|---|
| sub | User unique Profile ID in CY Login |
| name | Display name in CY Login |
| unique_identifier | Citizen ID / ARC Number / eIDAS Identifier if the profile is approved |
| legal_unique_identifier | Organisation Registration Number / eIDAS Identifier if the profile is approved. |
| legal_main_profile | If the user is the creator of the organisation profile (true or false) |
| Email used during registration | |
| profile_type | “Organisation” or “Individual” |
| client_ip | User IP address |
| acr | Authentication Level of assurance of the identity provider eidas-loa-loweidas-loa-substantialeidas-loa-high |
acr is used in case the relying party has specific security requirements. For example, if it requires all users to use electronic ids for authentication, they will restrict the users to the high level of assurance.
CY Login returns the following additional claims for European natural and legal persons who are authenticated though eIDAS network:
| Claim | Description |
|---|---|
| given_name | First name – string(50) |
| family_name | Last name – string(50) |
| birthdate | Date of birth : yyyy-mm-dd (1990-04-15) |
| legal_name | Organization Legal name |
2.3.4 Authorization Request
The following optional parameters can be used to customize the interaction with CY Login.
Relying parties requiring eID MUST use the acr_values and then check the returned acr claim to make sure that the user is logged in with the correct assurance level.
Also they MUST choose between prompt or max_age depending on their policies to make sure the user session is current and MUST verify the auth_time claim in the id_token that it meets the freshness requirements.
| Parameter | Supported Values | Description |
|---|---|---|
| ui_locales | el en | Change the CY Login UI language based on the client UI language. Greek / English |
| acr_values | eidas-loa-high eidas-loa-substantial | Authentication Level of assurance of the identity provider. If the user has an active session with CY Login that doesn’t match the requested level of assurance the user will be forced to login with an identity provider of the requested level. |
| prompt | login | Allows the client to force new authentication. Even if the user has an active session with CY Login he/she will be forced to login again. Make sure to check the auth_time claim in the id_token |
| max_age | to verify that the freshness of the user session. | |
| Seconds as integer number | Specifies the maximum allowed age for the SSO session (in seconds). If the session is older, the user is prompted to login again. Make sure to check the auth_time claim in the id_token to verify that the user session meets the requirements. |
2.3.5 CY Login Supported Flows
Depending on your use case, you will need to use a different OpenID Connect flow. Below you will find a table that maps application types to available CY Login OpenID Connect flows.
| Type of Application | OIDC Flow |
|---|---|
| Server-side (AKA Web) | Authorization Code Flow + PKCE, Authorization Code Flow, Hybrid (code id_token) |
| Single-Page Application (SPA) | Authorization Code Flow + PKCE |
| Native | Authorization Code Flow + PKCE |
2.3.6 TLS Requirements
The Relying Party application MUST use TLS 1.2 or greater.
2.3.7 Logout specification
The Relying Party MUST implement two specifications for logout.
- When the user clicks logout from the relying party the RP-Initiated Logout [5] MUST be implemented.
- When the user logouts from another relying party your relying party will be notified to terminate the user session (Single Sign Out – Front-Channel logout [6]).
3 APPENDIX A
3.1 What is OpenID Connect
OpenID Connect is an authentication standard built on top of OAuth 2.0. It adds an additional token called an ID token. OpenID Connect also standardizes areas that OAuth 2.0 leaves up to choose, such as scopes, endpoint discovery, and dynamic registration of clients.
Although OpenID Connect (OIDC) is built on top of OAuth 2.0, the specification uses slightly different terms for the roles in the flows:
- The “OpenID provider”, which is the authorization server that issues the ID token. In this case CY Login is the OpenID provider.
- The “end user” whose information is contained in the ID token.
- The “relying party”, which is the client application that requests the ID token from CY Login.
- The “ID token” is issued by the OpenID Provider and contains information about the End User in the form of claims.
- A “claim” is a piece of information about the End User.
The high-level flow looks the same for both OIDC and regular OAuth 2.0 flows, the primary difference being simply that an OIDC flow results in an ID token, in addition to any access or refresh tokens.
3.2 Authorization Code Flow
The Authorization Code flow is best used by server-side apps where the source code is not publicly exposed. The apps should be server-side because the request that exchanges the authorization code for a token requires a client secret, which will have to be stored in your client. The server-side app requires an end user, however, because it relies on interaction with the end user’s web browser which will redirect the user and then receive the authorization code.
3.3 Authorization Code Flow + PKCE
For web/native/mobile applications, the client secret cannot be stored in the application because it could easily be exposed. Additionally, mobile redirects use app:// protocols, which are prone to interception. Basically, a malicious application could intercept the authorization code as it is being passed through the mobile/native operating system. Therefore, native apps should make use of Proof Key for Code Exchange (PKCE), which acts like a secret but isn’t hard-coded, to keep the Authorization Code flow secure.
PKCE is an extension to the regular Authorization Code flow, so the flow is very similar, except that PKCE elements are included at various steps in the flow.
3.4 Hybrid Flow
The Hybrid Flow is an OpenID Connect (OIDC) grant that enables use cases where your application can immediately use an ID token to access information about the user while obtaining an authorization code that can be exchanged for an Access Token (therefore gaining access to protected resources for an extended period of time).
