General

Portrait supports the Authorization Code Flow for OAuth2 based authentication. The configuration is directly done via Spring Security Configurations.

After a successful login via the Oauth2 provider Portrait generates it’s own token authentication.
A logout from Portrait does NOT trigger a logout from the OIDC provider. Nor does a logout in the OIDC provider trigger a logout in Portrait.

A user can log in multiple times (from multiple devices) via the OAuth2 provider and will get signed in as the same user in Portrait each time.

When a user authenticates via OAuth2, a new Portrait account is automatically generated. We’ll refer to these OAuth2 accounts as oauth2-accounts. Depending on the configured provider, a username and email address are automatically assigned. An oauth2-account can not login via username+password based authentication. Therefore, all functions based on the password are deactivated for that user (password change, reset, …).

Each Portrait account can only be bound to one oauth2 provider.

Note that there can still be a separate portrait account with the same email address as an oauth2 account. These accounts are however in no way connected to eachother.

Configuration

Please make sure to read the warnings on the bottom of the page

In theory, any OAauth2 / OIDC provider can be used as long as they are conformed to the standard. In practice, it showed that often there are provider specific details. Especially when it comes to the extraction of the username and email address. For a more detailed configuration please consult the spring docs here. Below you will find a quick tl; dr for our supported providers:

RedirectUri

The redirectUri has be set correctly in both your configuration as well as an allowed redirect URL in your service provider (GitHub, Azure, …). It conistst of these parts

Complete:https://portrait.yourdomain.com/api/oauth2/login/code/github

Host:https://portrait.yourdomain.com → general domain your instanced is hosted. Can be an intranet URL as well. As long as your client can reach it during the authentication process.

Path: /api/oauth2/login/code/ → this is constant for every oauth provider

ProviderID: github → this is the name of the oauth provider you specified in the YML config.

Providers

The following providers are officially tested and supported in Portrait.

GitHub

Note that the login is not bound to a GitHub Organization. So anyone can login.

provided userinformation:

Userinformation	Supported

Userinformation	Supported
Name
Email

Configure an Oauth2 App here

The registration-id has to be github in order to work correctly.

spring:
  ...
  security:
    oauth2:
      client:
        registration:
          github:
            clientId: ...
            clientSecret: ...
            redirectUri: https://portrait.yourdomain.com/api/oauth2/login/code/github

The registration-id has to be github in order to work correctly.

Azure Entra Login

provided userinformation:

Userinformation	Supported

Userinformation	Supported
Name
Email

Configure an Oauth2 App here

(This guide is for single tenant apps, it should also work for multi tenant. More information can be found here multitenant app )

Note that the Oauth2 App should have the following permissions. It is sufficient to provide delegated permissions.

email
openid
User.Read

This means that you can use the following scopes for oauth2:

- openid
- email
- profile

The registration-id has to include one of these "microsoft", "office365", "azure" in order to work correctly. E.g azure-yourCompany

spring:
  ...
  security:
    oauth2:
      client:
        provider:
          azure:
            issuer-uri: https://login.microsoftonline.com/<tenant_id>/v2.0
        registration:
          azure-treskon:
            provider: azure
            client-id: ...
            client-secret: ...
            redirectUri: https://portrait.yourdomain.co/api/oauth2/login/code/azure-treskon
            client-name: Azure AD
            scope:
              - openid
              - email
              - profile

eIDAS

eIDAS are the foundation for an EU-wide, digital authentication service. Depending on the country, the state of the implementation differs, but the framework is the same.

Interoperability between countries is given

Although you have your business and portrait instance primarily in Austria, you can offer EU-citiziens the same functionality! eID auth can be forwarded to the respective authority in the user country.

In the following, we will elaborate how to connect with ID Austria as an reference. If you will use eIDAS primarily, with a different country, you need to check the respective endpoints.

ID Austria

Please read the general information about ID Austria first. Furthermore, check the information on how to create a Oauth2 App:

Note that there is a test system (“Q”), which can be used. However, you still need access to the https://www.usp.gv.at/ to set up your private instance.

Provided user information:

Userinformation	Supported

Userinformation	Supported
Name
Email

The registration-id has to include one of these "eidas", "eid", "idaustria", "id-austria", "id_austria", "digitalesamt", "digitalesoesterreich" in order to work correctly. E.g idaustria-yourcompany

spring:
  security:
    oauth2:
      client:
        provider:
          idaustria:
            issuer-uri: https://eid2.oesterreich.gv.at
        registration:
          idaustria:
            provider: idaustria
            clientId: ...
            clientSecret: ...
            redirectUri: https://portrait.yourdomain.com/api/oauth2/login/code/idaustria
            authorizationGrantType: authorization_code
            clientName: ID Austria
            scope:
              - openid
              - profile
              - eid

https://eid2.oesterreich.gv.at → Testsystem, Testusers https://eid.egiz.gv.at/anbindung/testidentitaeten/vordefinierte-testidentitaeten/

https://eid.oesterreich.gv.at → Productionsystem

Warnings

Registration ID

The registrationID should not be changed afterwards. This is because oauth2 accounts are bound to these. So when the registrationID changes a new oauth2 account will be created even tho an existing user logs in again

The registrationID also determines how the response from the Oauth2 Provider is parsed. So you should include the names that are listed for each oauth2 provider. See above.

Usage

Login Flow

1. Login via Provider

Login view within Portrait

Users can choose an login method an will be redirected to the login provider:

(This skip could be invisible to the user if they are already logged into the service provider, is that case a redirect back to portrait is automatically triggered)

Login via auth provider

2. Complete Registration in Portrait

It could be possible that the oauth provider already provides all the details that are required for a portrait registration. In this case this step is automaticallt skipped.

When a new user log into Portrait they might still be needed to fill our user details such as username and email address if the oauth provider did not provided these in the first place. The user will have a reduced featureset until he completes the registration process within portrait. This will look like this: