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

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:

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:

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

ID Austria - eIDAS

General Information https://www.oesterreich.gv.at/id-austria.html

Information on how to create a Oauth2 App:

https://eid.egiz.gv.at/anbindung/direkte-anbindung/anbindung-oidc/

https://eid.egiz.gv.at/anbindung/registrierung/registrierung-von-privaten-service-providern/

Note that there is a test system, which can be used. However you still need access to the https://www.usp.gv.at/

provided userinformation:

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.