Manage Federations

This page describes how to create and update federations for a tenant.

Before continuing, ensure you are familiar with:

The remainder of this document assumes that you have already authenticated the user and have obtained the authentication token necessary to invoke subsequent endpoints.

Getting Federation Information

Getting Existing Federations

Before starting, invoke the /federation/GetFederations endpoint to get the list of existing federations for the tenant:

POST https://tenant.my.centrify.net/Federation/GetFederations

{  
   "Args":{  
      "PageNumber":1,
      "PageSize":100000,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

The result field in the response contains a collection of objects describing each federation:

{  
   "success":true,
   "Result":[  
      {  
         "PartnerManageable":true,
         "FederationType":"SAML 2.0",
         "DirectLoginSupported":true,
         "FederationUuid":"45e142...",
         "Domains":[  
            "centrify.com"
         ],
         "FederationName":"DevDog",
         "Config":{  
            "SPSigningCertificateThumbprint":"30BEE0...",
            "IDPSigningCertificateThumbprint":"25CD...",
            "IDPSigningCertificateSubject":"CN=ABC1234.my.centrify.net, OU=dev, O=Centrify, L=SC, S=CA, C=US",
            "IDPSignInUrl":"https://tenant.my.centrify.net/run?appkey=35274...&customerId=tenant",
            "SPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
            "SPSigningCertificateExpires":"1/1/2039 12:00:00 AM",
            "IDPSigningCertificateCollection":[  
               {  
                  "IDPSigningCertificateSubject":"CN=ABC1234.my.centrify.net, OU=dev, O=Centrify, L=SC, S=CA, C=US",
                  "IDPSigningCertificateThumbprint":"25CDD...",
                  "IDPSigningCertificateExpires":"10/3/2034 11:21:18 PM"
               }
            ],
            "IDPSigningCertificateExpires":"10/3/2034 11:21:18 PM",
            "IDPLogoutUrl":"https://tenant.my.centrify.net/my?logout=true"
         },
         "Active":true
      }
   ],
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Getting Groups

Before a federation can be created or updated you need to identify a group to assign it to. Use the /federation/GetGroups endpoint to get a list of groups for the tenant:

POST https://tenant.my.centrify.net/Federation/GetGroups

The result field in the response contains the groups on the tenant:

{  
   "success":true,
   "Result":[  
      "External Users"
   ],
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Getting Global Federation Settings

You will also need to specify the federation settings when creating or updating a federation. Invoke the /federation/GetGlobalFederationSettings endpoint to get these settings:

POST https://tenant.my.centrify.net/Federation/GetGlobalFederationSettings?FederationType=SAML%202.0

The results field in the response contains the global federation settings:

{  
   "success":true,
   "Result":{  
      "GlobalMappings":[  

      ],
      "SPAutnenticationResponseUrl":"https://tenant.my.centrify.net/My",
      "SPMetadataUrl":"https://tenant.my.centrify.net/Federation/federationmetadata?FederationType=SAML%202.0",
      "SPSigningCertificateCAExpires":"1/1/2039 12:00:00 AM",
      "SPSigningCertificateCASubject":"CN=Centrify Customer AAA1234",
      "SPSigningCertificateCAThumbprint":"F29F1...",
      "SPSigningCertificateCAUrl":"https://tenant.my.centrify.net/Federation/SPSigningCertificateAuthority",
      "SPSigningCertificateExpires":"1/1/2039 12:00:00 AM",
      "SPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
      "SPSigningCertificateThumbprint":"30BEE0...",
      "SPSigningCertificateUrl":"https://tenant.my.centrify.net/Federation/SPSigningCertificate",
      "IDPEndpointUrl":"https://tenant.my.centrify.net",
      "RequestedAttributes":[  
         "Description",
         "DisplayName",
         "EmailAddress",
         "Group",
         "HomeNumber",
         "LoginName",
         "MobileNumber",
         "Name",
         "OfficeNumber",
         "Photo",
         "UserPrincipalName"
      ],
      "SPLogoutUrl":"https://tenant.my.centrify.net/Security/Logout",
      "SPLogoutReturnUrl":"https://tenant.my.centrify.net/My"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Getting Federation Types

A federation must be associated with a federation type. Invoke the /federation/GetFederationTypes endpoint to get the existing types:

POST https://tenant.my.centrify.net/Federation/GetFederationTypes

{  
   "Args":{  
      "PageNumber":1,
      "PageSize":100000,
      "Limit":100000,
      "SortBy":"",
      "direction":"False",
      "Caching":-1
   }
}

{  
   "success":true,
   "Result":[  
      "SAML 2.0"
   ],
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Creating a Federation

To create a new federation, invoke the /federation/CreateFederation endpoint passing in the group via the Mappings parameter and the type via the FederationType parameter. Note that all parameters are sent as multipart/form-data:

POST https://tenant.my.centrify.net/Federation/CreateFederation

Content-Length: 3853
Content-Type: multipart/form-data; boundary=----WebKitFormBoundarypFIjHqAe3F3QrD0d

------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationName"

TEST
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationType"

SAML 2.0
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Domains"

devdog.com
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Mappings"

[{"AttributeValue":"Test","GroupName":"External Users","undefined":""}]
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPMetadataUrl"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSignInUrl"

https://google.com
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPLogoutUrl"

https://google.com/logout
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCert_name"

Centrify SHA256 Tenant Signing Certificate (1).cer
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCertPassword"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationUuid"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCertificateThumbprint"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPMetadataUrl"

https://tenant.my.centrify.net/Federation/federationmetadata?FederationType=SAML%202.0
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPAutnenticationResponseUrl"

https://tenant.my.centrify.net/My
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificate_name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificateCA_name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPMetadataFileContents"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCert"; filename="Centrify SHA256 Tenant Signing Certificate (1).cer"
Content-Type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
MIIDEDCCAnmgAwIB.....+WICERdQ=
-----END CERTIFICATE-----

------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificate"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificateCA"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d--

The result field in the response contains the newly created federation:

{  
   "success":true,
   "Result":{  
      "Active":true,
      "Mappings":[  
         {  
            "AttributeValue":"Test",
            "GroupName":"External Users"
         }
      ],
      "FederationType":"SAML 2.0",
      "FederationName":"TEST",
      "FederationUuid":"5bbb8...",
      "DirectLoginSupported":true,
      "Domains":[  
         "devdog.com"
      ],
      "PartnerManageable":true,
      "Config":{  
         "IDPLogoutUrl":"https://google.com/logout",
         "IDPSigningCertificateThumbprint":"074FDEB...",
         "IDPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
         "SPSigningCertificateExpires":"1/1/2039 12:00:00 AM",
         "IDPSigningCertificateCollection":[  
            {  
               "IDPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
               "IDPSigningCertificateThumbprint":"074FDEB1...",
               "IDPSigningCertificateExpires":"1/1/2039 12:00:00 AM"
            }
         ],
         "SPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
         "IDPSignInUrl":"https://google.com",
         "SPSigningCertificateThumbprint":"30BEE0421C...",
         "IDPSigningCertificateExpires":"1/1/2039 12:00:00 AM"
      },
      "NormalizedFederationName":"test"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Updating a Federation

A federation can be updated by invoking the /federation/UpdateFederation endpoint. Note that all parameters are sent as multipart/form-data:

POST https://tenant.my.centrify.net/Federation/UpdateFederation

Content-Length: 2747
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryjW70PdyXRc7b8J79

------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationName"

TEST
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationType"

SAML 2.0
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Domains"

devdog.com
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="Mappings"

[{"AttributeValue":"Test","GroupName":"External Users","undefined":""}]
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPMetadataUrl"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSignInUrl"

https://google.com
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPLogoutUrl"

https://google.com/logout
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCert_name"

Centrify SHA256 Tenant Signing Certificate (1).cer
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCertPassword"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="FederationUuid"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCertificateThumbprint"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPMetadataUrl"

https://tenant.my.centrify.net/Federation/federationmetadata?FederationType=SAML%202.0
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPAutnenticationResponseUrl"

https://tenant.my.centrify.net/My
------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificate_name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificateCA_name"


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPMetadataFileContents"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="IDPSigningCert"; filename="Centrify SHA256 Tenant Signing Certificate (1).cer"
Content-Type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
MIIDEDCC...q+WICERdQ=
-----END CERTIFICATE-----

------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificate"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d
Content-Disposition: form-data; name="SPSigningCertificateCA"; filename=""
Content-Type: application/octet-stream


------WebKitFormBoundarypFIjHqAe3F3QrD0d--

The result field in the response contains the updated federation:

{  
   "success":true,
   "Result":{  
      "Config":{  
         "IDPLogoutUrl":"https://google.com/logout",
         "IDPSigningCertificateThumbprint":"074FDEB1...",
         "IDPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
         "SPSigningCertificateExpires":"1/1/2039 12:00:00 AM",
         "IDPSigningCertificateCollection":[  
            {  
               "IDPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
               "IDPSigningCertificateThumbprint":"074FD...",
               "IDPSigningCertificateExpires":"1/1/2039 12:00:00 AM"
            }
         ],
         "SPSigningCertificateSubject":"CN=Centrify Customer AAA1234 Application Signing Certificate",
         "IDPSignInUrl":"https://google.com/login",
         "SPSigningCertificateThumbprint":"30BEE0...",
         "IDPSigningCertificateExpires":"1/1/2039 12:00:00 AM"
      },
      "NormalizedFederationName":"test",
      "Active":true,
      "PartnerManageable":true,
      "FederationType":"SAML 2.0",
      "FederationName":"TEST",
      "FederationUuid":"5bbb8...",
      "Mappings":[  
         {  
            "AttributeValue":"Test",
            "GroupName":"External Users"
         },
         {  
            "AttributeValue":"Test2",
            "GroupName":"External Users"
         }
      ],
      "DirectLoginSupported":true,
      "Domains":[  
         "devdog.com"
      ]
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}