Skip to main content
Version: 13.x (Current)

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)
info

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.

danger

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.

NameTypeDescriptionDefaultOptional
namestringA unique name for the provider
typestringThe type of provider, one of okta, gitlab, github, microsoft, bitbucket, keycloak, generic
baseUrlstringThe url of the git provider
apiBaseUrlstringThe url of the git provider API andpointvalue of baseUrl
labelstringThe label to be shown to the final user
clientIdstringThe client Id for authentication
clientSecretstringThe client secret for authentication
authPathstringThe path for the authentication API
authUrlstringThe full url for the authentication APIvalue of apiBaseUrl/authPath
tokenPathstringThe path for retrieving the user token
tokenUrlstringThe full url for retrieving the user tokenvalue of apiBaseUrl/tokenPath
userInfoPathstringThe path for retrieving the user data
userInfoUrlstringThe full url for retrieving the user datavalue of apiBaseUrl/userInfoPath
userSettingsURLstringThe full url to the API endpoint for requesting the user dataempty string
skipRefreshProviderTokenOnMiaTokenRefreshbooleanSkip refresh the provider token when the console one is expiredtrue
cmsClientIdstringThe client Id for CMS authenticationvalue of clientId
cmsClientSecretstringThe client secret for CMS authenticationvalue of clientSecret
additionalScopesstring[]The additional scope for the provider[]
genericProviderOidcKeysobjectThe 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:

NameTypeDescriptionDefaultOptional
logoutUrlstringThe 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 listempty string
logoutUrlPathstringThe 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 listempty string

In case you set the logoutUrlPath, it will be appended to the Identity Provider base URL.

info

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:

NameTypeDescriptionDefaultOptional
jwtTokenPrivateKeyBase64stringThe private key file contents encoded to base64.
jwtTokenPrivateKeyPasswordstringThe password of the private key.
jwtTokenPrivateKeyKidstringThe KID of the private key. It can be any string, we suggest to generate an UUIDv4
tokenPassphrasestringAn 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
danger

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

NameTypeDescriptionDefaultOptional
enableUserSynchronizationWebhooksbooleanActivates 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

danger

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:

NameTypeDescriptionDefaultOptional
appstringA unique name for the app
isWebsiteAppbooleanHandle the website session or returns a jwt token in header
providersarrayThe providers configuration for authentication