for businessplayground
openid
eapi
rp management api

OpenID Connect

Overview

OpenID Connect 1.0 is a protocol for delegating user authentication. It is implemented as an identity layer on top of the OAuth 2.0 protocol considered being industry-standard, used by lots of identity providers on the internet today. It enables Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

Authentication is initiated by the Relying Party redirecting the user to Idfyed which responds after successful authentication.

The protocol is authentication-method agnostic.

Contents

Terminology

Terms not defined in the OpenID Connect Core specification list of Terminology:

Term description
Client According to Oauth 2.0
OP OpenID Provider, the Authorization server
amr Authentication Method
ID Token The user's identity in a signed token

Getting Started

The OP implements the Authorization Code Flow according to the OpenID Connect Core. This document will explain and give examples of each step of the flow.

Client Registration

For the Client to be able integrate with the OP, it needs credentials. These are obtained by providing Idfyed with the information listed below.

Information to provide to Idfyed

credential description
redirect_uri A URL where to send responses after authentication
amr Preferred Authentication Method Reference. See below
Available Authentication Methods
amr description
diglias Idfyed authentication
bankid Swedish BankID with the bankid client on the same unit
bankid-otherunit Swedish BankID with the bankid client on another unit
norbankid Norwegian BankID
telia Swedish Telia eID

Credentials to acquire from Idfyed

credential description
client_id OAuth 2.0 Client Identifier valid at the OP.
client_secret Client secret used in Token Request

Discovery

The OP has a Discovery Service Endpoint stating all information needed for integration with Idfyed's OpenID Connect implementation. It contains the different endpoints as well as signature keys to verify ID Tokens.

Migrate to Idfyed

If you already use OpenID Connect and want to add or migrate to Idfyed's OP, you need to reconfigure your existing implementation:

Integration

OpenID Connect and OAuth 2.0 are redirect protocols where the user agent is redirected to the OP and back to the Client to accomplish authentication.

Flow

The flow contain the following steps in the Authorization Code Flow.

  1. Client prepares an Authentication Request containing the desired request parameters.
  2. Client sends the request to the Authorization Server (OP).
  3. Authorization Server (OP) Authenticates the End-User.
  4. Authorization Server (OP) obtains End-User Consent/Authorization.
  5. Authorization Server (OP) sends the End-User back to the Client with an Authorization Code in an Authentication Response.
  6. Client sends a Token Request with the Authorization Code to the Token Endpoint (OP).
  7. Client receives a Token Response that contains an ID Token and Access Token in the response body.
  8. Client validates the ID Token and retrieves the End-User's Subject Identifier.

API Reference

Message Specification

Authentication Request

As specified in OpenID Connect: Authentication Request

An Authentication Request is an OAuth 2.0 Authorization Request that requests that the End-User be authenticated by the Authorization Server.

Parameter value
scope "openid"
client_id client_id
redirect_uri Where to redirect response, must be URI sent to Idfyed
state RECOMMENDED: Opaque value to keep state, returned in response. Must be Base64 encoded
nonce OPTIONAL: String to prevent replay attack, returned in ID Token. Must be Base64 encoded
ui_locales OPTIONAL: End-User's preferred languages, as a space-separated list of BCP47 (RFC5646) language tag values. If not included, End-User's browser settings will be used 
GET /main-oauth2/authz/begin?
    response_type=code
    &scope=openid
    &client_id=s6BhdRkqt3
    &state=af0ifjsldkj
    &nonce=gh28hkdsiouygh
    &locale=sv-SE
    &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1
Host: test.idfyed.com

Authentication Response

As specified in OpenID Connect: Authentication Response

An Authentication Response is an OAuth 2.0 Authorization Response message returned from the OP's Authorization Endpoint in response to the Authorization Request message sent by the RP.

Parameter value
code Code to claim in Token Request
state From the Authentication Request 
HTTP/1.1 302 Found
  Location: https://client.example.org/cb?
    code=SplxlOBeZQQYbYS6WxSbIA
    &state=af0ifjsldkj

Authentication Error Response

As specified in OpenID Connect: Authentication Error Response

An Authentication Error Response is an OAuth 2.0 Authorization Error Response message returned from the OP's Authorization Endpoint in response to the Authorization Request message sent by the RP. The OP returns the Client to the Redirection URI specified in the Authentication Request with the appropriate error, error_description and state.

Parameter value
state From the Authentication Request
error Error code, see spec for details
error_description Error description 
HTTP/1.1 302 Found
Location: https://client.example.org/cb?
    error=invalid_request&
    error_description=Unsupported%20response_type%20value&
    state=af0ifjsldkj

Token Request

As specified in OpenID Connect: Token Request

A Client makes a Token Request from its own backend to the OP's Token Endpoint by presenting its Authorization Grant (in the form of the Authorization Code from the Authentication Response) using the grant_type value authorization_code. It's important that the call is done from the backend of the Client and that the client_secret is never exposed outside the Client's server.

Parameter value
grant_type "authorization_code"
code From the Authentication Response
client_id client_id
client_secret client_secret
redirect_uri Same as Authentication Request 
POST /api-oauth2/token/ HTTP/1.1
  Host: test.idfyed.com
  Content-Type: application/x-www-form-urlencoded

  grant_type=authorization_code&
  code=SplxlOBeZQQYbYS6WxSbIA&
  client_id=s6BhdRkqt3&
  client_secret=SECRET&
  redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Token Response

As specified in OpenID Connect: Token Response

The endpoint returns a successful response that includes an ID Token.

Parameter value
access_token Access token, not used
token_type "Bearer"
id_token ID Token, see ID Token chapter 
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"refresh_token": "8xLOxBtZp8",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
 yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
 NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
 fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
 AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
 Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
 NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
 QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
 K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
 XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

Token Error Response

As specified in OpenID Connect: Token Error Response

In cases of error, the token endpoint returns an HTTP 400 (Bad Request) with the body of a json encoded error.

Parameter value
error Error code, see spec for details
error_description Error description 
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error_description": "Transaction not found: 96d7f1006bab885b9ed4f5022e5b4805",
    "error": "invalid_request"
}

ID Token

The ID Token is a signed JWT token.

ID Token verification and validation.

Before trusting the ID Token it must be verified and validated locally on the Client's server. For debugging purposes, you can use the tokeninfo endpoint

Verifying JWT

The ID Token is signed by a private signature key and can be verified by one of the keys specified in the jwks_uri pointed out by the Discovery Service Endpoint.

The ID Token must also be validated according to OpenID Connect: ID Token.

Key rotation

Since the signature key is changed at intervals, the Client must be able to handle that. The OpenID Connect specification explains how to do that.

Verifying JWT using tokeninfo service

For debugging purposes, the tokeninfo endpoint can be used to validate and parse the ID Token.

GET /api-oauth2/tokenoinfo?id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdk HTTP/1.1

If the token is properly signed it will return the ID Token in json format.

HTTP/1.1 200 Ok
Content-Type: application/json
{
  "sub": "1abb7bb9-899b-4f5c-9fe2-32fb293c9885",
  "email_verified": false,
  "address": {
    "country": "SE"
  },
  "gender": "male",
  "amr": "diglias",
  "kid": "1234",
  "iss": "http://test.idfyed.com/api-oauth2",
  "exp": 1592982721,
  "alg": "RS256",
  "email": "hello@idfyed.com"
}

ID Token content

The content of the ID Token depends on what amr is used and how it is configured which is decided when registering the Client.

Changelog

v1.0

Initial version of this document

References

  • RFC 6749 The OAuth 2.0 Authorization Framework, D. Hardt, Ed., 2019
  • OpenID Connect Core OpenID Connect Core 1.0 incorporating errata set 1, Nat Sakimura, John Bradley, Michael B. Jones, Breno de Medeiros, Chuck Mortimore, 2014
  • JWT JSON Web Token (JWT), Jones, M., Bradley, J., and N. Sakimura,