Ariadni – Cy-Login Specifications

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


document are to be interpreted as described in RFC 2119 [1].

1.5        References

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:

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:

subUser unique Profile ID in CY Login
nameDisplay name in CY Login
unique_identifierCitizen ID / ARC Number / eIDAS Identifier if the profile is approved
legal_unique_identifierOrganisation Registration Number / eIDAS Identifier if the profile is approved.
legal_main_profileIf the user is the creator of the organisation profile (true or false)
emailEmail used during registration
profile_type“Organisation” or “Individual”
client_ipUser IP address
acrAuthentication 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:

given_nameFirst name – string(50)
family_nameLast name – string(50)
birthdateDate of birth : yyyy-mm-dd (1990-04-15)
legal_nameOrganization 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.

ParameterSupported ValuesDescription
ui_localesel enChange the CY Login UI language based on the client UI language. Greek / English
acr_valueseidas-loa-high   eidas-loa-substantialAuthentication 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.
promptloginAllows 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 numberSpecifies 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 ApplicationOIDC Flow
Server-side   (AKA Web)Authorization Code Flow + PKCE,   Authorization Code Flow, Hybrid (code id_token)
Single-Page Application (SPA)Authorization Code Flow + PKCE
NativeAuthorization 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).

Print Friendly, PDF & Email