GuidesAPI ReferenceGitHub
Guides
Community ForumsTwitter

Privilege Elevation

Centrify can be configured to require additional authentication in order to elevate a user's access privilege.

This page describes the API workflow for programmatically elevating a user's privilege through MFA.

The example used to demonstrate this involves a user trying to launch an application through the User Portal. The application has been configured with a policy that requires elevated privilege before access is granted. In this example, the user must satisfy additional MFA challenges upon clicking the application before the it will launch. This displays an MFA popup through which the user must satisfy the challenges defined by the policy. Once the user successfully fulfills these challenges, the application then runs using the elevated privilege granted.

Before continuing, ensure you are familiar with:

Step 1. Handle the App Click to get the Challenge ID and Log the User In

Invoke the /uprest/HandleAppClick endpoint passing the application's key via the appkey query parameter:

GET /uprest/HandleAppClick?appkey=12341234-8181-401d-958a-8b98a5c40e7a

The response contains a redirect URL to the login screen which includes the application key and a query parameter named elevate which contains the challenge ID for use in subsequent calls:

<html><head><title>Object moved</title></head><body>
<h2>Object moved to <a href="/login?appkey=12341234-8181-401d-958a-8b98a5c40e7a&amp;antixss=OFlq4t_UbQRUqrLc2kgneQ__&amp;elevate=bRJAUCmuKEKKkiXOEmwoEZxmpsRi...">here</a>.</h2>
</body></html>

Invoke the URL:

GET /login?appkey=12341234-8181-401d-958a-8b98a5c40e7a&antixss=OFlq4t_UbQRUqrLc2kgneQ__&elevate=bRJAUCmuKE&challengeId=bRJAUCmuKE

The response contains login information in HTML:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Content-Type: text/html; charset=utf-8
Expires: -1
Vary: Accept-Encoding
X-CFY-TX-PN: Pod0
X-CFY-TX-ID: b77ace72548a412...
X-CFY-TX-DT: Mi8yNy8yMDE4ID...
X-Frame-Options: SAMEORIGIN
P3P: CP="NON COR ADMa CURa DEVa OUR IND COM UNI NAV INT PRE LOC ONL PHY STA ONL"
X-UA-Compatible: IE=8,9,10
Strict-Transport-Security: max-age="31536000"
X-CFY-TX-TM: 117
Set-Cookie: antixss=2HVBWoMLg3n2wAdfz...; path=/; secure
Set-Cookie: sessdata=L3dVSFFVRkJNREF3TkF...; path=/; secure; HttpOnly
Set-Cookie: podloc=eyJkZXZkb2cuY2VudHJpZnkuY29tIj...; domain=centrify.com; expires=Fri, 31-Dec-9999 23:59:59 GMT; path=/; secure
Set-Cookie: userdata=eyJEYXRhIjoiL3dVSFFVRk...; expires=Thu, 29-Mar-2018 15:47:12 GMT; path=/; secure
X-Robots-Tag: noindex, nofollow
Date: Tue, 27 Feb 2018 15:47:11 GMT
Content-Length: 7640


<!DOCTYPE html>
<html>
<head>
    <!-- Page setup -->
    <title>User Portal</title>
    <meta http-equiv="X-UA-Compatible" content="IE=8,9,10" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <link rel="shortcut icon" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/logos/centrify-16-1.png"/>

    <!-- CSS includes -->
    <link href='/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/fonts/Roboto.css?_ver=1519716991' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/fonts/Icon-Set.css?_ver=1519716991' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/standalonelogin/login.css?_ver=1519716991' rel='stylesheet' type='text/css'>

    <!-- Window style -->
    <style type="text/css">
        embed {display:none; width:0; height:0; padding:0; margin:0;}
        html,
        body {
            height: 100%;
            width: 100%;
            margin: 0px;
        }

        .no-script-alert {
            background: #fff;
            text-align: left;
            padding: 10px 20px 10px 45px;
            border-top: 2px solid #ffd324;
            border-bottom: 2px solid #ffd324;
        }
    </style>

    <script type="text/javascript">
        /**
        * Creating a config object that the glued JavaScript can reference without being in an
        * ASP.NET context.
        */
        var AuthData = {"TenantConfig":{"NavigationColor":"","PreloadRoleMemebership":false,"MobileLocationHistoryTrackingEnabled":false,"Brand":"centrify","SmsSystemEnabled":true,"InternetGatewayAllowed":true,"AllowPhonePin":true,"UserLocationEnabled":true,"BackgroundColor":"","GoogleClientEnabled":true,"Enab...},
            ManifestName: "login",
            ResourceBase: "/vfslow/lib/ui/",
            Version: "1519716991",
            Locale: "en-us",
            LoginImage: "/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/logos/centrify-breach-stops-here.png",
            LoginSampleText: "user@domain or user@suffix",
            EnabledSocialUserIdps : "",
            Environment: "Azure",
        };

    </script>
</head>
<body class='centrify-login'>

    <!-- Warning for disabled javascript -->
    <noscript><p class="no-script-alert">JavaScript is currently not supported/disabled by this browser. Please enable JavaScript for full functionality.</p></noscript>

    <!-- Locale strings -->
    <script src="/vfslow/lib/ui/standalonelogin/locale/en.js?_ver=1519716991"></script>

    <!-- IE8 compatibility scripts -->
    <script src="/vfslow/lib/ui/standalonelogin/compatibility/ie8.js?_ver=1519716991"></script>
    <script src="/vfslow/lib/ui/standalonelogin/compatibility/classList.js?_ver=1519716991"></script>

    <script src="/vfslow/lib/ui/../uibuild/standalonelogin/login.js?_ver=1519716991"></script>

    <script type="text/javascript">
        document.addEventListener('DOMContentLoaded', function () {
            LaunchLoginView({
                containerSelector: '.centrify-login'
            });
        });
    </script>
</body>
</html>

Step 2. Start the Elevation Challenge using the Challenge ID

Start the authentication process by invoking the /Security/StartChallenge and passing the challenge ID via the ChallengeStateId parameter:

POST /Security/StartChallenge

{  
   "TenantId":"",
   "User":"[email protected]",
   "Version":"1.0",
   "AssociatedEntityType":"Portal",
   "AssociatedEntityName":"Portal",
   "ExtIdpAuthChallengeState":"",
   "ChallengeStateId":"bRJAUCmuKEKKk..."
}

The response contains the list of MFA challenges that must be satisfied. In the following example, the user has the option to receive a verification code by email or SMS:

{  
   "success":true,
   "Result":{  
      "ClientHints":{  
         "PersistDefault":false,
         "AllowPersist":false,
         "AllowForgotPassword":false
      },
      "Version":"1.0",
      "SessionId":"T0zrHgE6kkKdj...",
      "Challenges":[  
         {  
            "Mechanisms":[  
               {  
                  "AnswerType":"StartTextOob",
                  "Name":"EMAIL",
                  "PromptMechChosen":"Click the link in the email sent to [email protected]",
                  "PromptSelectMech":"Email... @centrify.com",
                  "PartialAddress":"centrify.com",
                  "MechanismId":"YpaLLR3lMk6qQktKEnw753..."
               },
               {  
                  "AnswerType":"StartTextOob",
                  "Name":"SMS",
                  "PartialDeviceAddress":"4567",
                  "PromptMechChosen":"Sending a text to mobile phone ending... 4567. Enter the code or click the link in the message to proceed with authentication.",
                  "PromptSelectMech":"SMS... XXX-4567",
                  "MechanismId":"Wdf7j9cqyu6Ymo..."
               }
            ]
         }
      ],
      "Summary":"NewPackage",
      "TenantId":"AAA0004"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Step 3.A Advance the Authentication

Invoke the /Security/AdvanceAuthentication endpoint for each challenge. In the example below, the endpoint is being invoked to start the Oob challenge where a verification code is sent to the user via SMS:

POST /Security/AdvanceAuthentication

{  
   "TenantId":"AAA0004",
   "SessionId":"T0zrHgE6kkKdjs...",
   "PersistentLogin":null,
   "MechanismId":"Wdf7j9cqyu6Ymoq...",
   "Action":"StartOOB"
}

The Summary response indicates that the verification code has been sent:

{  
   "success":true,
   "Result":{  
      "Summary":"OobPending"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

When the verification code has been entered, invoke the /Security/AdvanceAuthentication endpoint passing the user's answer via the Answer field:

{  
   "TenantId":"AAA0004",
   "SessionId":"T0zrHgE6kkKdj...",
   "PersistentLogin":null,
   "MechanismId":"Wdf7j9cqyu6Ymoqp...",
   "Answer":"abcd1234",
   "Action":"Answer"
}

The success field in the response indicates that the user successfully fulfilled the challenge:

{  
   "success":true,
   "Result":{  
      "SystemID":"AAA0004",
      "DisplayName":"J N",
      "EmailAddress":"[email protected]",
      "CustomerID":"AAA0004",
      "AuthLevel":"High",
      "PodFqdn":"mycorp.centrify.com",
      "Auth":"DE01F612EC5B81DD05E...",
      "User":"[email protected]",
      "UserDirectory":"AdProxy",
      "Summary":"LoginSuccess",
      "UserId":"abcd1234-b5f5-4995-a500-70859b6adbf7",
      "SourceDsType":"AdProxy"
   },
   "Message":null,
   "MessageID":null,
   "Exception":null,
   "ErrorID":null,
   "ErrorCode":null,
   "InnerExceptions":null
}

Step 3.B Re-invoke the Handle App Click Endpoint (Required only for Auth Profiles)

If you are launching an app from outside of the App Portal with an Auth Profile where Pass through duration is set to No Pass Through, then the you must invoke the /uprest/HandleAppClick endpoint again, passing the challenge ID via the challengeId URL parameter or as a header (X-CFY-CHALLENGEID). For example:

GET /uprest/HandleAppClick?appkey=12341234-8181-401d-958a-8b98a5c40e7a&challengeId=bRJAUCmuKE

Note: in this case you will receive a new ASPXAUTH token that you must use in the next step.

Step 4. Run the Application using the Challenge ID

Now that the authentication has completed, the user is now elevated and can run the application. Invoke the /run endpoint passing the application's key via the appkey query parameter and the challenge ID via the elevate and challengeId parameters:

GET /run?appkey=12341234-8181-401d-958a-8b98a5c40e7a&antixss=OFlq4t_UbQRUqrLc2kgneQ__&elevate=bRJAUCmuKEKK...&challengeId=bRJAUCmuKEKK...

The response contains the HTML to render the application:

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Content-Type: text/html; charset=utf-8
Expires: -1
Vary: Accept-Encoding
X-CFY-TX-PN: Pod0
X-CFY-TX-ID: 452357ecdadf4801b...
X-CFY-TX-DT: Mi8yNy8yMDE4I...
X-Frame-Options: SAMEORIGIN
P3P: CP="NON COR ADMa CURa DEVa OUR IND COM UNI NAV INT PRE LOC ONL PHY STA ONL"
X-CFY-TX-TM: 182
Set-Cookie: antixss=80nDUH_nsn...; path=/; secure
Set-Cookie: sessdata=L3dVSFFVRkJNREF3TkFK...; path=/; secure; HttpOnly
Set-Cookie: podloc=eyJkZXZkb2cuY2VudHJ...; domain=centrify.com; expires=Fri, 31-Dec-9999 23:59:59 GMT; path=/; secure
Set-Cookie: userdata=eyJEYXRhIjoiL3dVSFFVR...; expires=Thu, 29-Mar-2018 15:47:55 GMT; path=/; secure
X-Robots-Tag: noindex, nofollow
Date: Tue, 27 Feb 2018 15:47:54 GMT
Content-Length: 4334

<!DOCTYPE html>
<html>
<head>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <meta content="text/html; charset=UTF-8" http-equiv="content-type" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />

    <link href='/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/fonts/Roboto.css?_ver=1519716991' rel='stylesheet' type='text/css'>
    <link href='/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/fonts/Icon-Set.css?_ver=1519716991' rel='stylesheet' type='text/css'>

        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_01.css?_ver=1519716991"/>
        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_02.css?_ver=1519716991"/>
        <link rel="stylesheet" type="text/css" href="/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/centrify-all_03.css?_ver=1519716991"/>

    <script src="/vfslow/lib/ui/jsutil/resources/locale/en.js?_ver=1519716991"></script>
        <script src="/vfslow/lib/ui/jsutil/resources/locale/en.js?_ver=1519716991"></script>

    <style type="text/css">
        html {
            height: 100%;
            margin: 0;
        }
        h2 {
            font-weight: normal;
            text-rendering: optimizeLegibility;
        }
        body {
            background: #ececec !important;
            overflow-y: hidden;
            font-family: 'Roboto';
            font-size: 13px;
        }
    </style>

    <script type="text/javascript">
        var ServerConfig = {
            UIStringFile: "/vfslow/lib/ui/jsutil/resources/locale/en.js",
            SkinDef:  {"themeColor":"#363a40","theme":"centrify","adminRegisTxtCSSCls":"","cssDirectory":"compiled/centrify/production/resources","emailImage":"/logos/logo-centrify-1.png","footer":{"termsUrl":"https://www.centrify.com/eula/","copyrightText":"&copy; 2004-{0} Centrify Corporation.","termsText":"footer_term","privacyUrl":"https://www.centrify.com/privacypolicy.asp","privacyText":"footer_policy"},"navigationColor":"#979797","loginCssDirectory":"compiled/jsutil/production/resources","backgroundColor":"#FFFFFF","newHelpRoot":"{helpRootServer}/","proxy":{"download64Bit":"Cloud-Management-Suite-win64.zip"},"pageIcon":"/logos/centrify-16-1.png","helpDirectoryBrandName":"","mfa":{"waitGif":"/ellipses_anim.gif","stepsFolder":"/steps/"},"loginImage":"/logos/centrify-breach-stops-here.png","macEnrollDialogImage":"/enroll/centrify-macs.png","brand":"centrify","helpRoot":"{helpRootServer}/{1}/centrify/{2}/index.html","name":"Centrify","portalImage":"/logos/centrify-main-logo.png","aboutWindowIcon":"/logos/centrify-main-logo.png"},
            LoginImage: "/vfslow/lib/ui/../uibuild/compiled/centrify/production/resources/images/logos/centrify-breach-stops-here.png",
            LightRadialColor: "",
            DarkRadialColor: "",
            LightLinearColor: "",
            DarkLinearColor: "",
            CBEVersion:  '1.164.1803',
            CBEUrl: 'https://edge.clouddev.centrify.com/CBE/Centrify/Firefox/1.164.1803/CentrifyFirefoxExtension.xpi',
            IsCBEPinned: 'False',
            IsCBECheckPrompt: 'True',
            ResourceBase: '/vfslow/lib/ui/',
            Locale: "",
            Version: '1519716991',
            LoadBase: "",
            ManDef: {
                restUrl: ''
            }
        };
    </script>

    <script src="/vfslow/lib/ui/../uibuild/compiled/jsutil/production/app-all.js?_ver=1519716991"></script>
</head>
<body class='browser-extension-install'>
    <div id="top-line" class='topLine' style='border-top: 6px solid'></div>
    <div id="outer-panel" class="outerPanel"></div>
    <div id="app-launch-panel"></div>

    <script type="text/javascript">
        window.Jsutil.bypassLogin = true;
        Ext.onReady(function () {
            Ext.require('Jsutil.cbeutil', function () {
                document.getElementById('top-line').style['border-color'] = window.ServerConfig.SkinDef.navigationColor;
                CbeUtil.showInstallView(true);
            });
        });
    </script>


</body>
</html>

Try the API in Postman:
Try the API in Postman.
Click here for help with using our sample Postman collection.

Updated about 5 years ago