Linking or Unlinking SAML Users

Linking or Unlinking SAML Users

You can link a SAML user account to a Telerik Platform user account, allowing the user to log in with either. You can unlink the SAML user account at any time, keeping the Telerik Platform user management functionality.

See the coverage in Introduction to SAML Login Integration for more details.

You need the SAML assertion for the user to perform linking. The way you obtain the assertion depends on whether you are implementing active federation or passive federation.

Linking with a SAML Account

You link a SAML IdP user account to an existing Telerik Platform user account by making a POST request to the link endpoint of the built-in Users content type. The request must be authorized by a Telerik Platform bearer token valid for the specific user or by your MasterKey.

In the payload, set the UTL-encoded SAML security token that you obtained earlier and set the provider name to SAML.

Request:
    POST https://api.everlive.com/v1/your-app-id/Users/item-id/link
Headers:
    Content-Type: application/json
    Authorization:  Bearer your-access-token
Payload - raw:
    {
        "Provider": "SAML",
        "Token": "your-URL-encoded-SAML-token"
    }
Response:
    Status: 200 OK
    Content-Type: application/json
    Body: {}
var user = {
    "Provider": "SAML",
    "Token": "your-URL-encoded-SAML-token"
};
$.ajax({
    type: "POST",
    url: 'https://api.everlive.com/v1/your-app-id/Users/item-id/link',
    headers: {"Authorization" : "Bearer your-access-token"},
    contentType: "application/json",
    data: JSON.stringify(user),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

These are important points you need to know about linking:

  • The user who you are linking must be logged in to their Telerik Platform account (in other words, you need the Telerik Platform access token to perform linking).
  • Users who have linked their SAML IdP identity to their Telerik Platform account can log in using either of them.
  • The SAML IdP user profile is stored as an object in the user account's Identity.SAML field. It is visible only when using MasterKey authentication or when using Bearer authentication but the access token is issued for the same user.
  • If the Telerik Platform user account's Email is empty and the SAML IdP user profile contains an email, then it is stored in the user account's Email field.
  • You cannot link a single SAML IdP account to multiple Telerik Platform user accounts. If you try this, you receive an error.

Unlinking from a SAML Account

You unlink a SAML IdP user account from an existing Telerik Platform user account by making a POST request to the unlink endpoint of the built-in Users content type. The request should be authorized by a Telerik Platform bearer token valid for the specific user or by your MasterKey. In the payload, set the Provider to SAML.

Request:
    POST https://api.everlive.com/v1/your-app-id/Users/item-id/unlink
Headers:
    Content-Type: application/json
    Authorization:  Bearer your-access-token
Body:
    { "Provider": "SAML" }

Response:
    Status: 200 OK
    Content-Type: application/json
    Body: {}
var user = {
    "Provider": "SAML"
};
$.ajax({
    type: "POST",
    url: 'https://api.everlive.com/v1/your-app-id/Users/item-id/unlink',
    headers: {"Authorization" : "Bearer your-access-token"},
    contentType: "application/json",
    data: JSON.stringify(user),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

These are important points you need to know about unlinking:

  • The user who you are unlinking must be logged in to their Telerik Platform account (in other words, you need the Telerik Platform access token to perform unlinking).
  • Telerik Platform deletes the user's SAML IdP profile by setting Profile.SAML to null in the user account object.
  • After a user has been unlinked you can relink them.
  • The users can unlink only their own SAML IdP account. They cannot unlink other users' SAML IdP accounts, even if they have update permissions for the Users content type. This restriction is not present when using MasterKey authentication.
  • You can only unlink user accounts that existed before linking them to an AD account.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.