Authentication Provider
In order to authenticate users Mia-Platform Console requires a connection to an Identity Provider that is in charge of authenticate users.
Supported Authentication Providers
Any OAuth2
compliant Identity Provider is supported, however Mia-Platform Console provides specific integrations with most IDPs, here is a comprehensive list, each provider identified by an id that can be used during configuration:
- Okta (
okta
) - Keycloak (
keycloak
) - GitLab (
gitlab
) - GitHub (
github
) - Microsoft (
microsoft
) - Bitbucket (
bitbucket
)
For provider not listed here, you can use the generic
authentication provider to configure your own.
Configure your Authentication Provider
To connect Mia-Platform Console with your Authentication Provider you have to setup the authProviders
configuration.
Please bear in mind that the authProviders
field is a required field, you can't install Mia-Platform Console without configuring at least one Authentication Provider.
Name | Type | Description | Default | Optional |
---|---|---|---|---|
name | string | A unique name for the provider | ❌ | |
type | string | The type of provider, one of okta , gitlab , github , microsoft , bitbucket , keycloak , generic | ❌ | |
baseUrl | string | The url of the git provider | ❌ | |
apiBaseUrl | string | The url of the git provider API andpoint | value of baseUrl | ✅ |
label | string | The label to be shown to the final user | ❌ | |
clientId | string | The client Id for authentication | ❌ | |
clientSecret | string | The client secret for authentication | ❌ | |
authPath | string | The path for the authentication API | ✅ | |
authUrl | string | The full url for the authentication API | value of apiBaseUrl/authPath | ✅ |
tokenPath | string | The path for retrieving the user token | ✅ | |
tokenUrl | string | The full url for retrieving the user token | value of apiBaseUrl/tokenPath | ✅ |
userInfoPath | string | The path for retrieving the user data | ✅ | |
userInfoUrl | string | The full url for retrieving the user data | value of apiBaseUrl/userInfoPath | ✅ |
userSettingsURL | string | The full url to the API endpoint for requesting the user data | empty string | ✅ |
skipRefreshProviderTokenOnMiaTokenRefresh | boolean | Skip refresh the provider token when the console one is expired | true | ✅ |
cmsClientId | string | The client Id for CMS authentication | value of clientId | ✅ |
cmsClientSecret | string | The client secret for CMS authentication | value of clientSecret | ✅ |
additionalScopes | string[] | The additional scope for the provider | [] | ✅ |
genericProviderOidcKeys | object | The keys that must be extracted from the provider response, only available for generic auth provider type | ✅ |
Logout flow
You can configure the Console to logout the user from the Identity Provider when the user logs out from the Console itself. In oder to do so, you have to set one of the following properties:
Name | Type | Description | Default | Optional |
---|---|---|---|---|
logoutUrl | string | The full URL to perform a logout from an OIDC compliant provider. If you are configuring a generic provider, make also sure to add openid to the additionalScopes list | empty string | ✅ |
logoutUrlPath | string | The path to append to the API endpoint to perform a logout from an OIDC compliant provider. If you are configuring a generic provider, make also sure to add openid to the additionalScopes list | empty string | ✅ |
In case you set the logoutUrlPath
, it will be appended to the Identity Provider base URL.
Please note that you may need to allow the redirect URL to the homepage of the Console and to the homepage of the CMS login site inside the Identity Provider configuration.
The urls are the following:
<CONSOLE-BASE-URL>/
<CONSOLE-CMS-BASE-URL>/web-login
Consult the documentation of your Identity Provider to know how to configure the redirect URLs.
Session signing
Even though the authentication is resolved by a third party, the sessions provided by Mia-Platform Console to its users are signed by the console itself, by means of the RSA256 asymmetric algorithm.
To be able to properly manage users authentication, the Console requires a few additional configurations, to be set under the key userAccountAuthProvider
:
Name | Type | Description | Default | Optional |
---|---|---|---|---|
jwtTokenPrivateKeyBase64 | string | The private key file contents encoded to base64. | ❌ | |
jwtTokenPrivateKeyPassword | string | The password of the private key. | ❌ | |
jwtTokenPrivateKeyKid | string | The KID of the private key. It can be any string, we suggest to generate an UUIDv4 | ❌ | |
tokenPassphrase | string | An HMAC string of 128 bytes for authentication purpose, used to encrypt sensitive data saved to Redis. You can generate it with a command like openssl rand -base64 128 | ❌ |
The latest version of the chart introduces the asymmetric signing of the users JWT tokens, thus the token won't be signed and verified anymore with the old symmetric jwtTokenSignKey
, but signed with a private key and verified with a public key.
This may cause 401 errors to be shown to users that still have an old token signed with the old key.
The user may need to manually navigate to the Console login page to be able to login again. A new token signed with the new private key will then be issued.
Private key generation
The Console supports the RSA256 asymmetric algorithm to sign JWT Tokens. You need to provide a password protected PEM private key, of at least 4096 bytes.
Here is a command you can use to generate it:
ssh-keygen -t rsa -b 4096 -m PEM -f private.key
When prompted, specify a password, the same you will set in jwtTokenPrivateKeyPassword
.
The command generates two files: private.key
and private.key.pub
.
We can discard the public key:
rm private.key.pub
and copy a base64
representation of the private key:
cat private.key | base64 | pbcopy
You can now delete the private.key
file:
rm private.key
Expose synchronization webhooks
If you want to control user creation and deletion from an external Identity Provider you can use the enableUserSynchronizationWebhooks
configuration flag
Name | Type | Description | Default | Optional |
---|---|---|---|---|
enableUserSynchronizationWebhooks | boolean | Activates webhooks for automatic user synchronization with external Identity providers | ✅ |
To know more about user synchronization with an Identity Provider, visit the dedicated documentation page.
Additional Authentication Clients
This feature is deprecated and will be removed with v10 of the Mia-Platform Console Installation Chart!
With the additionalAuthenticationClients
you can set up more providers by defining a list of object with the following properties:
Name | Type | Description | Default | Optional |
---|---|---|---|---|
app | string | A unique name for the app | ❌ | |
isWebsiteApp | boolean | Handle the website session or returns a jwt token in header | ❌ | |
providers | array | The providers configuration for authentication | ❌ |