Authorization-Code-Flow

The Authorization API provides authentication to Europace for APIs. It is a mandatory requirement for using Europace APIs.

Documentation

Usecases

onboard user of any organization to integrate Europace in a tool
login user after user-approval

Quickstart

To test our APIs and your use case as quickly as possible, we’ve put together a Postman Collection for you.

How to get users access_token with Europace auth-code-flow

The diagram is showing the flow and steps of the authorization process.

%%{init: {'theme': 'neutral', 'themeVariables': { 'actorBkg': '#83EEED'}}}%%
sequenceDiagram
  autonumber
  participant usr as User
  participant br as  Browser
  participant app as User Application
  participant auth as Authorization API 
  participant ep as Europace API
  Note over usr, ep: user interaction
  activate usr
  usr ->> app: show ressource of Europace
  activate br
  activate app
  app ->> br: redirect ep-auth<br/> with state
  deactivate app
  br ->> auth: authorize response-type=code<br/> (example 1)
  activate auth
  auth ->> auth: user authenticated?
  auth ->> br: show login-page (no)
  usr ->> br: input username & pw  
  br ->> auth: username & pw
  auth ->> auth: client-approval exists?
  auth ->> br: show user-consent-page (no)
  usr ->> br: approve client & scope
  br ->> auth: approve client & scope
  auth ->> auth: create client-approval
  auth ->> br: redirect to redirect_uri<br/> with code & state
  Note over usr, ep: backend interaction
  br ->> app: code & state
  activate app
  app ->> app: check state
  app ->> auth: auth with code<br/> (example 2)
  auth ->> app: access_token &<br/> id_token
  deactivate auth
  app ->> app: decode id_token to identify user<br/> and store `sub` at user-data<br/> for later use (optional)
  app ->> ep: call EP-API with access_token
  ep ->> app: ressource-data
  app ->> br: show ressource-data
  usr ->> br: 😍
  deactivate app
  deactivate br
  deactivate usr

User interaction part

After client-registration, you can create a link for the browser to get an id-token after user-authentication and user-consent for your client (step (3) in the diagram):

This request is for all users the same and doesn’t contain sensible information.

example request 1:

https://www.europace2.de/authorize
?response_type=code
&client_id=[client-id]
&redirect_uri=[redirect-uri]
&scope=[registered and needed scopes]%20openid
&state=[yourDataForRedirectUri]
&prompt=select_account

This link will start the authentication process in the browser. The user will be authenticated (step 4) and give the user-consent (step 8) for the requested scopes and the client.

Backend interaction part

To close the registration-circle, we call back the redirect-uri in the browser with path-param code and state (step 13). If user already authenticated and user-consent already exists, the browser will directly redirect to your redirect-uri.

Europace will redirect to: [redirect-uri]?code=[oneTimeCode]&state=[yourDataForRedirectUri]

example request 2:

https://client.example.org/?code=GGu48n-64cQen4gu&state=HelloWorld

State can be used to pass information through the process like sessions, user-id or security-handles.

With the code you can get an id-token for the authenticated user (step (2) in the diagram). Use your client-id and client-secret as basic authentication credentials for POST-Form with grant-type, code and redirect-uri. Usually, the redirect-uri has to be encoded.

Example-Request:

POST /auth/token HTTP/1.1
Host: api.europace.de
Authorization: Basic VlVIN...
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=GGu48n-64cQen4gu
&redirect_uri=https%3A%2F%2Fclient.example.org%2F

Example-Response:

{
   "access_token": "eyJraWQiO...",
   "scope": "openid profile baufinanzierung:vorgang:schreiben profile baufinanzierung:vorgang:lesen",
   "id_token": "eyJraWQiOiJPTE...",
   "token_type": "Bearer",
   "expires_in": 3600
}

The access_token can now used with al Europace APIs.

In the process, problems could occur. In most problem-cases, we will provide the code but you can not get an access-token. You will get an error-message, which you can handle. The process ends unsuccessfully.

Possible problems:

use declined the user-consent
user are not allowed to use the client

How to identify the user (optional)

To get the partnerId if the user, inspect the id-token with decoding RSA256, and extract the sub-property. The id_token contains user-information in the payload if scope=profile is used. You will find a lot of libs for your prefered code-language at www.jwt.io to decode jwt-tokens with RSA256.

Requirements:

valid id_token

Example decoded id-token with scope=openid:

{
  "sub": "ABC12",
  "aud": "XMLM6XIG5JALVM3V",
  "auth_time": 1620743169,
  "iss": "https://api.europace.de",
  "exp": 1620752934,
  "iat": 1620745734,
  "jti": "cS_ZHi80_W958vNV"
}

Example decoded id-token with scope=profile openid:

{
  "sub": "ABC12",
  "iss": "https://api.europace.de",
  "preferred_username": "theo.test@example.org",
  "given_name": "Theo",
  "picture": "https://www.europace2.de/partnermanagement/d71c58aeaed4022384b169f83e0d8842.avatar?anonymousAvatar=BENUTZER
",
  "aud": "VUH5WE2SVDPBDJFD",
  "auth_time": 1620741571,
  "vo": "YOUR_ORGANISATION",
  "exp": 1620748826,
  "iat": 1620741626,
  "family_name": "Test",
  "email": "theo.test@example.org",
  "jti": "uW12IT_krnR0Zyrp"
}

sub contains the authenticated partnerId. You can store the partnerId on your user-data to get an access-token in the future without any user-interaction.

How to get an access-token without user-interaction (optional)

If you need access-token for backend-jobs, where the user is not present, you can get one with the partnerId of the user.

This step is not shown in the diagram.

Requirement:

To get the access-token use your client-id and client-secret as basic authentication credentials for POST-Form with grant-type, scope, actor and subject

example request:

POST /auth/token HTTP/1.1
Host: api.europace.de
Authorization: Basic VlVIN...
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&scope=[registered and needed scopes]
&actor=[user partnerId]
&subject=[user partnerId]

example response:

If your client is valid and the user-consent exists and all requested scopes are registered on the client and approved by the user you should receive an access-token.

{
   "access_token": "eyJraWQiOi..",
   "scope": "baufinanzierung:vorgang:schreiben baufinanzierung:vorgang:lesen openid profile",
   "token_type": "Bearer",
   "expires_in": 3600
}