General
Portrait supports the Authorization Code Flow for OAuth2 based authentication. The configuration is directly done via Spring Security Configurations.
...
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
| Note |
|---|
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
...
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.
...
The registration-id has to be github in order to work correctly.
Azure Entra Login
provided userinformation:
...
| Code Block |
|---|
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
...
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.
| Info |
|---|
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 https://www.oesterreich.gv.at/id-austria.htmlInformation first. Furthermore, check the 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 (“Q”), which can be used. However, you still need access to the https://www.usp.gv.at/provided userinformation to set up your private instance.
Provided user information:
Userinformation | Supported |
|---|---|
Name |
|
|
...
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
...
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)
...
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.
...
The missing user details can be set in the Account Settings
...
3. Get Verified by an Admin
After a user has provided all the details needed for registration an admin still needs to set the user to status granted in order to use Portrait.
...
Afterwards, the user can use all features of Portrait. (reloading the site via the browser is necessary.
...
If configured, the user will also receive a mail that their account is unlocked and ready to use.
...