Identity providers

Tip: You can perform all team management actions with the Account Management API.

An identity provider (IdP) manages users’ authentication when they attempt to log in to Portal. The IdP options are:

• Pelion Device Management (Native): The user needs to create a Portal password to log in. This option is always available.
• mbed.com: The user can use the existing Mbed password to log in. This option is not always available – your account administrator must configure this.
• Custom provider: The user does not need a Portal or Mbed account. Instead, the user can log in with a third-party identity provider, such as your own company’s IdP. Portal accepts the verification token from the IdP. Device Management supports both OpenID Connect (OIDC) or SAML 2.0 providers, but account administrators must set up OIDC.

In Portal, you can:

• Add a custom IdP for your team.
• Edit a custom IdP.
• Renew a custom IdP’s signing certificate.
• Generate or renew a service provider certificate for a custom IdP.
• Activate or suspend a custom IdP.
• Delete a custom IdP.

You can only manage your own custom IdPs; you cannot edit the global providers in Portal. If you experience problems with one of the global providers, please contact your account administrator.

Adding a custom IdP

To add a new IdP:

1. In Team Configuration > Identity and security, click New ID provider.

2. The New Identity Provider connection pop-up opens.

3. Select the IdP type: OIDP or SAML2.

4. Enter a name and, optionally, a description.

5. The following fields are for settings your IdP provides; if you are not sure what to enter, please verify with the IdP:

   For OIDC:

   • Issuer: The ISS identifier of the IdP. Must be unique for the deployment.
   • Redirect URI: We recommend you leave it unspecified; it will be autogenerated. You must then configure the redirect URI in your IdP to match the generated value.
   • Client ID: To authenticate and gain access to identity provider's API.
   • Client Secret: To authenticate and gain access to identity provider's API.
   • Enable OIDC auto-discovery mechanism: Enable if your IdP supports it; otherwise, leave disabled and enter the parameters manually:
     • Authorization endpoint of the IdP for authentication requests.
     • Token endpoint of the IdP for exchanging the authorization code for an access token.
     • Userinfo endpoint (optional).
     • End session endpoint (optional). Leave it empty if you want to disable Single Log Out.
     • Revocation endpoint of the IdP for cleaning up any security credentials associated with the session in the IdP side.
     • JSON web keys (JWKS) URI for the IdP's signing certificates. If the URI is available, these keys are read automatically. If you don't have a valid URI, add keys manually (click Add a key).

   For SAML2:

   You can upload an XML descriptor if you received one from your IdP, or enter your settings manually:

   • IdP entity ID (URN): Must match the entity ID the IdP provides.
   • Single Sign On (SSO) URL: URL for the IdP's Single Sign On action.
   • Single Log Out (SLO) URL: URL for the IdP's Single Log Out action.
   • Service Provider (SP) entity ID (optional), which you need to give to your IdP when you complete this setup process. We recommend you leave it unspecified; it will be autogenerated.
   • IDP X.509 certificate: You must provide at least one X.509 signing certificate in PEM format. (You should have received one from your IdP.) Click Add certificate.

6. Click Save.

7. The IdP is added to your team.

You can now select this IdP when inviting new users. You can also move existing users to this IdP (from the users' Security details).

Editing a custom IdP

To edit an IdP:

1. In Team Configuration > Identity and security, click the IdP's name.
2. The Identity provider pane opens.
3. Click the Edit button.

The editing process is identical to the initial creation process, as explained above.

Renewing an IdP signing certificate

An IdP must have valid certificates to authenticate users. If the certificate expires or is incorrect in any way, users can't log in with their IdP credentials, and their active sessions may be closed. You must therefore renew a certificate before it expires.

Normally, IdP administrators publish a new signing certificate before they start using it. Device Management can keep both certificates and attempt to validate against both, so you can add the new certificate before the old one expires and not remove the old one. This will ensure a smooth transition between certificates. When the IdP starts using the new certificate, you can delete the old one.

Please ensure your IdP has your new certificate before making any changes on the Portal side. If there is a mismatch between the certificate on Portal and the one with your IdP, user authentication will fail.

To add the new signing certificate to your IdP:

1. In Team Configuration > Identity and security, click the IdP's name.

2. The Identity provider pane opens.

3. Click the Edit button.

4. The New SAML2 Identity Provider connection page opens.

5. Under the Identity provider X.509 signing certificate field, click Add another certificate.

6. Add the new certificate.

   At this point, don’t delete or replace the old one.

7. Click Save.

   You are asked to enter your password.

8. Device Management now has both your current and your new certificates.

Please remember to delete the old certificate when your IdP changes to the new one.

Generating or renewing a service provider certificate

For SAML2, your IdP may request that you provide a service provider (SP) certificate. If that happens, you can generate a certificate from Portal. You can also renew that certificate before it expires.

To generate or renew an SP certificate:

1. In Team Configuration > Identity and security, click the IdP's name.

2. The Identity provider details pane opens.

3. In the Certificates section, click Renew (this button is also valid for generating the first certificate).

   You are warned that the action cannot be undone and that the old certificate will no longer work. Confirm the warning to continue, or cancel the warning to stop the process.

4. Device Management generates an updated certificate.

5. The certificate now applies to the IdP, and the authentication request in the SAML2 protocol will be signed by the new SP certificate.

Suspending, activating or deleting a custom IdP

You can manage security for an IdP by suspending it if you become suspicious of its security, for example if you have reason to believe user credentials from the IdP have been compromised. You can then either activate it again if you think it’s safe, or delete it entirely.

Every IdP represents an access point to your system. As best practice, you should delete any custom IdP you aren’t using.

To change an IdP’s status:

1. In Team Configuration > Identity and security, click the IdP's name.

   The Identity provider details pane opens.

2. To:

   • Suspend an active IdP or activate a suspended IdP, click the status buttons.

   • To delete the IdP, click the Delete button.

     You cannot delete an IdP that has any users associated with it; you have to associate those users with another IdP first (through the user’s security details).

Using IdPs

• You can use your IdPs when creating a new user.
• You can change an existing user's IdP.