Configuring ServiceNow for Groups

Once you connect EmpowerID to ServiceNow, you can configure ServiceNow to create EmpowerID groups, and to synchronize groups and manage them within EmpowerID. This topic demonstrates how to configure ServiceNow to work with EmpowerID.

Prerequisites:

To configure ServiceNow to create EmpowerID groups, you need the following values from EmpowerID.

  • Username - the EmpowerID admin
  • Password
  • Fully Qualified Domain Name(FQDN)*
  • OAuth Client ID**
  • OAuth Client Secret**

*The FQDN for EmpowerID is part of the URL that you use to log in. It is the bold portion of this example URL:

https:// sso.empowersso.com/EmpowerID/

These values authenticate EmpowerID to ServiceNow. You also need an admin account in EmpowerID to supply ServiceNow with the credentials to create groups in EmpowerID.

**The OAuth client information is available under Admin > SSO Connections > OAuth, in the DefaultSystemOauthApplication.

In ServiceNow, you need to create the following.

  • An OAuth provider that contains the information needed to connect with EmpowerID so that REST messages can be passed.
  • Two new properties in the Request [sc_request] table to use in the Resume HTTP method of the REST message.
    • workflowinstanceid
    • workflowcorrelationid
  • A REST message that calls the EmpowerID REST API with three POST HTTP methods.
    • Default POST: for starting the workflow on the ServiceNow side
    • Access Token: to get an access token for web API calls
    • Resume Workflow POST: for starting the workflow on the EmpowerID side
  • A Business Rule on the Approval table that tracks EmpowerID group requests in the Approval table, and passes values to the REST message.
  • A ServiceNow workflow to handle user requests from the service catalog.
  • A service catalog request so users can request EmpowerID groups through ServiceNow.

To create an OAuth provider

The OAuth provider contains the information needed to connect with EmpowerID so that REST messages can be passed.

  1. Log in to your ServiceNow instance, and in the navigation pane, search for Application Registry and select it.
  2. Above the list of Application Registries, click the New button, and select Connect to a third party OAuth Provider.
  3. Configure the new Application Registry with the following settings. (Skipped settings can retain their default values.)
    • Name - EID
    • Client ID - The GUID from your EmpowerID OAuth application Client ID (Key)
      To find your EmpowerID OAuth settings in the web UI, expand Admin, then SSO Connections, and click OAuth. You can find all of the client settings in the DefaultSystemOauthApplication.
    • Client Secret - The GUID from your EmpowerID OAuth application Client Secret
    • OAuth API Script - Click the search icon and select OAuthUtil.
    • Authorization URL - https:// FQDN/oauth/v2/ui/authorize

    • Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).
    • Token URL - https:// FQDN/oauth/v2/token
    • Redirect URL - https:// FQDN/EmpowerIdWebIdPForms/oauth/v2
  4. Scroll to the bottom, and on the OAuth Entity Profiles tab, double-click the text Insert a new row and enter these values.
    • Name - EID default_profile
    • Is default - true
    • Grant type - Resource Owner Password Credentials
  5. Click Submit to save the OAuth provider.

To add new columns to the Request table

Add two columns to the ServiceNow Request table to use in the Resume HTTP method parameters. The Resume method collects these values, along with the IsApproved value, via the HTTP query parameter script to pass to EmpowerID.

  1. Log in to your ServiceNow instance, and in the navigation pane, search for Tables and select the one under System Definition.
  2. Above the list of Tables, change the Go to drop-down from Name to Label, and search for Request.
  3. Click the Request [sc_request] table.
  4. On the Columns tab, click the New button to add a new Correlation ID column with the following settings. (Skipped settings can retain their default values.)
    • Type - String
    • Column label - Correlation ID
    • Column name - (autofills after a pause) u_correlation_id
    • Max length - 255
    • Active - selected
    • Display - selected
  5. Click Submit to save the new column.
  6. Back on the Columns tab, click the New button to add a new Workflow Instance ID column with the following settings. (Skipped settings can retain their default values.)
    • Type - String
    • Column label - Workflow Instance ID
    • Column name - (autofills after a pause) u_workflow_instance_id
    • Max length - 255
    • Active - selected
  7. Click Submit to save the new column.
  8. Back on the Request table, click Update to save the new columns to the Request table.

To create a REST message

The REST message is what passes information between ServiceNow and the EmpowerID REST API. It uses three methods to communicate via EmpowerID's anonymous endpoints. One method passes access tokens, another responds to group requests created in EmpowerID with approval or rejection, and the third notifies EmpowerID to create a group from a request in the ServiceNow services catalog.

  1. In the navigation pane, search for REST Message and select it.
  2. Above the list of REST Messages, click the New button.
  3. Configure the new REST message with the following settings.
    • Name: EmpowerID API
      Take note of the name you use, as it is used in the Creating an Approval Business Rule script below.
    • Accessible from - All application scopes
    • Endpoint - https:// FQDN/oauth/v2/token
      Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).
  4. On the Authentication tab, change the Authentication type to OAuth 2.0. For the OAuth profile, click the search icon and select the EID default_profile that you created earlier.

  5. On the HTTP Request tab, add two HTTP Headers.

    1. In the list of HTTP Headers, double-click the text Insert a new row and enter these values.
      • Name - Content-Type
      • Value - application/json
    2. Insert another new row and enter these values.
      • Name - X-EmpowerID-API-Key
      • Value - your EmpowerID OAuth application API key
    You can find your OAuth application API key in EmpowerID by expanding Admin, then SSO Connections,and selecting OAuth. Click to open the DefaultEmpowerIDOAuthApplication, then click the Display Name to open it for editing. There you can copy the API Key for use in ServiceNow.
  6. Click Submit to save the REST message. Back on the REST Messages list, click your newly created EmpowerID API REST message. A message at the top directs you to click the Get OAuth Token link to request a token.
  7. Click the link, supply your ServiceNow admin Username and Password, and click Get OAuth Token.
  8. Back on the EmpowerID API message, scroll to the bottom to see the HTTP Methods list.
  9. Next to HTTP Methods, click the New button to create a new POST method. Create three in total, with the following settings. (Click Submit after each to return to the main REST Message page where you can add the next.)

    Access Token HTTP Method

    • Name - Access Token
      Take note of the name you use, as it is used in the Creating an Approval Business Rule script below.
    • HTTP method - POST
    • Endpoint - https:// FQDN/oauth/v2/token
      Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).
    • On the Authentication tab, change the Authentication type to Basic. For the Basic auth profile, create a new one.
      1. Click the search icon to the right of the field, and in the Basic Auth Configurations window that opens, click the New button.
      2. Configure the new Basic Auth Configuration with the following settings.
        • Name - EID
        • Username - Enter your EmpowerID admin username
        • Password - Enter your EmpowerID admin password
      3. Click Submit to save the profile, and back on the Authentication tab, for the Basic auth profile, select the newly created EID.
    • On the HTTP Request tab, add two HTTP Headers.
      1. In the list of HTTP Headers, double-click the text Insert a new row and enter these values.
        • Name - Content-Type
        • Value - application/json
      2. Insert another new row and enter these values.
        • Name - X-EmpowerID-API-Key
        • Value - your OAuth application API key
        You can find your OAuth application API key in EmpowerID by expanding Admin, then SSO Connections, and selecting OAuth. Click to open the DefaultSystemOauthApplication, then click the Display Name to open it for editing. There you can copy the API Key for use in ServiceNow.
      3. Below the HTTP Query Parameters, paste the following code into the Content box.
      4. 
            { 
               "client_id": "GUID from your Client ID (Key)", 
               "client_secret": "GUID from your Client Secret",
               "redirect_uri": "https://FQDN/empoweridwebidpforms/oauth/v2",  
               "grant_type": "password" 
            }
            
        Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com) and the GUIDs with values from your OAuth application in EmpowerID. To find these, expand Admin, then SSO Connections, and select OAuth. Click to open the DefaultSystemOauthApplication, then click the Display Name to open it for editing. There you can copy the Client ID (Key) and Client Secret GUIDs for use in ServiceNow.

    Default POST HTTP Method

    • Name - Default POST
      Take note of the name you use, as it is used in the Creating an Approval Business Rule script below.
    • HTTP method - POST
    • Endpoint - https:// FQDN/api/services/v1/workflow/start
      Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).
    • On the Authentication tab, change the Authentication type to No authentication.
    • On the HTTP Request tab, add three HTTP Headers.
      1. In the list of HTTP Headers, double-click the text Insert a new row and enter these values.
        • Name - Authorization
        • Value - Bearer ${Token}
      2. Insert another new row and enter these values.
        • Name - Content-Type
        • Value - application/json
      3. Insert third row and enter these values.
        • Name - X-EmpowerID-API-Key
        • Value - your OAuth application API key
      4. You can find your OAuth application API key in EmpowerID by expanding Admin, then SSO Connections, and selecting OAuth. Click to open the DefaultSystemOAuthApplication, then click the Display Name to open it for editing. There you can copy the API Key for use in ServiceNow.
      5. Below the HTTP Query Parameter section, enter the following script in the Content box, replacing NNNN and NNNNN with the values described below.
        
            { 
                "Name": "CreateGroup",
                "TaskType":"Workflow",
                "InputParameters": 
                {
                    "TargetGroup" : 
                    {
                        "GroupTypeID":9,
                        "AllowJoinRequests":true,
                        "Name":"${Name}",
                        "Description":"${Description}",
                        "AccountStoreID": NNNN
                    },
                    "TargetOrgZone" : {"OrgZoneID" : NNNNN},
                    "RequestInitiatedFromServiceNow" : true,
                    "DecisionOfRequestInitiatedFromSN": "${Decision}"
            }
                                                

        Replace NNNN with the Account Store ID from your ServiceNow Account Store in EmpowerID.

        1. In the web UI, expand Admin, then Account Stores and Systems.
        2. On the Account Stores tab, click ServiceNow and copy the Account Store ID value.

        Replace NNNNN with the ServiceNow OrgZoneID in your EmpowerID SQL database. You can find it in SQL Server Management Studio.

        1. In SQL Server Management Studio, expand the Databases node, and select the EmpowerID database.
        2. In the toolbar, click New Query, enter the query: select * from orgzone and click Execute.
        3. In the list of results, find ServiceNow and copy the OrgZoneID.

    Resume HTTP Method

    • Name - Resume
      Take note of the name you use, as it is used in the Creating an Approval Business Rule script below.
    • HTTP method - POST
    • Endpoint - https:// FQDN/api/services/v1/workflow/resume
      Replace "FQDN" with the fully qualified domain name of your EmpowerID server (e.g. sso.empoweriam.com).
    • On the Authentication tab, change the Authentication type to No authentication.
    • On the HTTP Request tab, add three HTTP Headers.
      1. In the list of HTTP Headers, double-click the text Insert a new row and enter these values.
        • Name - Authorization
        • Value - Bearer ${Token}
      2. Insert a second new row and enter these values.
        • Name - Content-Type
        • Value - application/json
      3. Insert a third new row and enter these values.
        • Name - X-EmpowerID-API-Key
        • Value - your EmpowerID OAuth application API key
      4. You can find your OAuth application API key in EmpowerID by expanding Admin, then SSO Connections, and selecting OAuth. Click to open the DefaultSystemOauthApplication, then click the Display Name to open it for editing. There you can copy the API Key for use in ServiceNow.
      5. Below the HTTP Query Parameter section, enter the following script in the Content box.
        {
               "InstanceId": "${WorkflowInstanceID}",
               "CorrelationId": "${CorrelationId}", 
               "Name" : "CreateGroup",
               "InputParameters": {
                   "Decision": "${IsApproved}"
               },
               "OutputParameters": ["*"]
            }
                                                
  10. Click the Submit button to save the REST message.
  11. When you get the message telling you to click the Get OAuth Token link, click the link and supply your EmpowerID admin username and password.
  12. Click the Get OAuth Token button
  13. Click the Update button to save the REST message.

To create an Approval Business Rule

The Approval table, where ServiceNow tracks EmpowerID group approval requests and their results, needs a business rule to pass values to the REST message.

  1. Log in to your ServiceNow instance, and in the navigation pane, scroll down and expand System Definition, then find and select Business Rules. (You can also search for Business Rules, and select the one nested under System Definition.)
  2. Above the list of Business Rules, click the New button, and add a new one named EmpowerID BR.
  3. Configure the new business rule with the following settings.
    • Name - EmpowerID BR
    • Application - Global (default)
    • Table - Approval [sysapproval_approver]
    • Active - selected (default)
    • Advanced - selected (shows an advanced tab below, and adds fields)
  4. On the When to run tab, set When to "after," and select the Update checkbox.
  5. On the Advanced tab, paste this script to replace the default stub.
  6. (function executeRule(current, previous /*null when async*/) {
        
            // Code to create response for EmpowerID and update the Approval table
        try
            {
                var r = new sn_ws.RESTMessageV2("EmpowerID API", "Access Token");
                var response = r.execute();
                var responseBody = response.getBody();
                var parser = new JSONParser();
                var parsed = parser.parse(responseBody);
                var t = parsed.access_token;
                
                var regRecord = current.document_id.getRefRecord();
                if(regRecord.getValue('u_workflow_instance_id') != null)
                {
                    var r1 = new sn_ws.RESTMessageV2("EmpowerID API", "Resume");
                    r1.setStringParameterNoEscape("Token", t);
                    r1.setStringParameterNoEscape("WorkflowInstanceID", regRecord.getValue('u_workflow_instance_id'));
                    r1.setStringParameterNoEscape("CorrelationId", regRecord.getValue('u_correlation_id'));
                    r1.setStringParameterNoEscape("IsApproved", current.state);
                    var response1 = r1.execute();
                    var responseBody1 = response1.getBody();
                    var httpStatus1 = response1.getStatusCode();
                }
                else
                {
                    var req_item = new GlideRecord('sc_req_item');
                    req_item.addQuery('request', regRecord.sys_id);
                    req_item.query();
                    if(req_item.next())
                    {  		
                        var r2 = new sn_ws.RESTMessageV2("EmpowerID API", "Default POST");
                        r2.setStringParameterNoEscape("Token", t);
                        r2.setStringParameterNoEscape("Name", req_item.variables["GroupName"].toString());
                        r2.setStringParameterNoEscape("Description", req_item.variables["GroupDescription"].toString());
                        r2.setStringParameterNoEscape("Decision", current.state);
                        var response2= r2.execute();
                        var responseBody2= response2.getBody();
                        var httpStatus2 = response2.getStatusCode();
                    }
                }
            }
            catch(ex) 
            {
                var message = ex.getMessage();
            } 
        
        })(current, previous);
                        
  7. Click Submit to save the business rule.

To create a Workflow

This is where you set up the workflow to run when a user requests an EmpowerID group from the service catalog.

  1. Log in to your ServiceNow instance, and in the navigation pane, search for Workflow Versions and select it.
  2. Above the list of Workflow Versions, click the New button, and add a new workflow named EmpowerID WF.
  3. Configure the new workflow version with the following settings.
    • Name - EmpowerID WF
    • Table - Request [sc_request]
  4. On the Conditions tab, leave the default value of Run the workflow (or Run the workflow always) with no conditions.
  5. On the Stages tab, leave the default value of Stage field and change the Stage rendering value to Legacy.
  6. Click Submit to save the workflow version. A new tab opens with the visual workflow designer.
  7. From the Core tab on the right, drag workflow activities onto the designer to create a workflow like the one in this image using the settings below.
  8. In the window that pops up for each activity, use the following settings.
  9. Set Requested

    • Folder - Utilities
    • Activity - Set Values
    • Name - Set Requested
    • Values --field-- - Approval
    • Values --value-- - Requested
    • Click Submit.
    • Click the dark yellow dot on the default Begin activity and drag it to your new activity to create a flow arrow.

    Short Description starts with 'EmpowerID'

    • Folder - Conditions
    • Activity - If
    • Name - Short Description starts with 'EmpowerID'
    • Condition --choose field - Short description
    • Condition --choose operator - starts with
    • Condition --(string) - EmpowerID
    • Click Submit.
    • Click the dark yellow dot on the Set Requested activity and drag it to your new activity to create a flow arrow.

    Send for approval to Sys Admin

    • Folder - Approvals
    • Activity - Approval - User
    • Name - Send for approval to Sys Admin
    • Approvers --Users - System Administrator
    • Condition for approval - use default values
    • Schedule --Due date based on - A relative duration
    • Schedule --Relative duration - 2 business days by 4pm
    • Schedule --Schedule based on - A user specified schedule
    • Schedule --Schedule - 8-5 weekdays
    • Click Submit.
    • Click the dark yellow dot on the Short Description starts with 'EmpowerID' activity's Yes option and drag it to your new activity to create a flow arrow.
    • Click the dark yellow dot on the Short Description starts with 'EmpowerID' activity's No option and drag it to the End activity to create a flow arrow.

    Approved

    • Folder - Approvals
    • Activity - Approval Action
    • Name - Approved
    • Action - Mark task approved
    • Click Submit.
    • Click the dark yellow dot on the Send for approval to Sys Admin activity's Approved option and drag it to your new activity to create a flow arrow.
    • Click the dark yellow dot on the Approved activity and drag it to the End activity to create a flow arrow.

    Rejected

    • Folder - Approvals
    • Activity - Approval Action
    • Name - Rejected
    • Action - Mark task rejected
    • Click Submit.
    • Click the dark yellow dot on the Send for approval to Sys Admin activity's Rejected option and drag it to your new activity to create a flow arrow.
    • Click the dark yellow dot on the Rejected activity and drag it to the End activity to create a flow arrow.
  10. Click the Validate button (checkbox) above the workflow to ensure that it works.
  11. Click the hamburger menu at the top left and select Publish to make your workflow available to all users.
  12. Back on the browser tab with the EmpowerID WF workflow version, click Submit to save your changes.
  13. If you need to edit the workflow, click the Show Workflow link at the bottom of the EmpowerID WF worflow version.

To create a service catalog request

The service catalog request provides a page in the ServiceNow service catalog where users can request a new EmpowerID group.

  1. Log in to your ServiceNow instance, and in the navigation pane, search for Maintain Items and select it. (Or navigate to Service Catalog, then Catalog Definitions, and select it from there.)
  2. Above the list of Catalog Items, click the New button, and add a new catalog item.
  3. Configure the new catalog item with the following settings.
    • Name - EmpowerID Service Catalog Request
    • Catalogs - Service Catalog
    • Category - Services
    • Short Description - Request EmpowerID Group
    • Description - Create a group request. Once approved the group will be created in EmpowerID.

  4. Click Submit, then open the EmpowerID Service Catalog Request from the list of catalog items. (Change the Go to value to Name to search for it.)
  5. On the Variables tab at the bottom of the page, click New to add a variable with the following settings.
    • Question - Group Description
    • Name - GroupDescription
    • Tooltip - Enter a description for the group.

  6. Click Submit to save the variable.
  7. Back on the Variables tab, click New to add a second variable with the following settings.
    • Question - Group Name
    • Name - GroupName
    • Tooltip - Enter the name of the group.
  8. Click Submit to save the second variable.
  9. On the Approved By tab at the bottom of the page, click Edit to add an approver for EmpowerID group requests.
  10. In the Collection search box, find and select System Administrator, and click the Add arrow to add it to the Approved By List.
  11. Click Save to save the approver.
Once you have connected EmpowerID to ServiceNow, you can view and manage the users and groups associated with it from the ServiceNow Manager page in EmpowerID, located at "https://<YourEmpowerIDServer>/UI/#Common/Find/ServiceNowManager."