Multiple Role Support

Anthony - Versasec Support
Anthony - Versasec Support
  • Updated

Introduction

Multiple roles are where a user within an organization has more than one Windows account (or role). In a multi forest environment, a user may have several different Windows accounts across multiple active directories (AD). Therefore, when issuing a credential for such a user it is required to be able to issue multiple certificates for the user associated with each different Windows account.

For example, a Windows user has 2 administration accounts: adminrole1 and adminrole2. It is required that this user is issued with 2 certificates which will be used to then authenticate the user when required as either adminrole1 or adminrole2.

Before describing how to configure multiple role support it is important to understand how this works in the vSEC:CMS.

1: When a credential is being issued to a user in vSEC:CMS, the user will be selected from a directory, typically AD. The credential will be assigned a user identifier (ID). This ID will be the Distinguished Name (DN) from AD and will be referred to as the primary user role in this section.

2: The vSEC:CMS will take the DN from 1 and depending on the rules configured for a role to derive a user DN it will attempt to retrieve the DN for the configured role. There are different mechanisms in place to attempt to derive the DN for a given role template. These are:

2 a): If Generated (Generate ID from distinguished name (DN)) mechanism is used to derive the DN then the vSEC:CMS will take the DN returned in 1 and apply the rules set in the role template and derive the DN for the user.

2 b): If Generated (Generate ID from account name (sAMAccountName)) mechanism is used then the vSEC:CMS will take the DN returned in 1 and retrieve the Windows account name (sAMAccountName) for this DN. vSEC:CMS will then apply the rules set in the role template and derive the Windows account name for the user. Then vSEC:CMS will take this value and retrieve from the AD configured in the role template the DN for this Windows user account.

2 c): If Generated (Generate ID from UPN) is used then vSEC:CMS will take the DN returned in 1 and retrieve the Windows UPN for this DN. vSEC:CMS will then apply the rules set in the role template and derive the Windows UPN for the user. Then vSEC:CMS will take this value and retrieve from the AD configured in the role template the DN for this Windows UPN.

2 d): If Select (Manually select user) is used then it will be possible to manually select the user from the selected AD. It will then be possible to manually issue a certificate for the user after the credential has been issued from Actions - Certificate(s)/Keys.

2 e): If From variable (ID stored in a variable) is used then vSEC:CMS will retrieve the users DN from an attribute that the variable is assigned to. vSEC:CMS will then search the AD configured to retrieve the user.

2 f): If From query (Run LDAP query to retrieve ID) is used then vSEC:CMS will use the configured LDAP query to retrieve the unique identifier for the user that is shared across the multiple ADs.

3 : The certificate requests can now be processed. Depending on the CA that is used and what is configured in the certificate template, either the DN or the Windows account name will be sent to the CA to request the CA to issue the certificates for the user.

Configure Support

This section will describe each of the multiple role mechanisms in detail.

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list several options will appear.

Generated (Generate ID from distinguished name (DN))

If this option is selected then it will be possible to configure what prefix or suffix that can be added to a specific DN field, for example the CN field. Additionally, it is possible to perform a search and replace operation on the DN in order to derive the user ID from the selected primary user during the issuance. If both options are configured then the prefix or suffix operation will be performed first followed by search and replace operation.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the credential issuance.

For example, if the primary user that would be selected has a DN of:

CN=Admin Role,OU=role1,DC=versasec,DC=com

And in the User DN field the value CN was entered and in the Suffix field a value of 2 was entered. Additionally, if the Search field had a value of role1 and Replace had a value of role2 then vSEC:CMS would try to retrieve a user with following DN from the user directory:

CN=Admin Role2,OU=role2,DC=versasec,DC=com

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

Generated (Generate ID from account name (sAMAccountName))

If this option is selected then it will be possible to configure what prefix or suffix that can be added to a specific Windows account name. Additionally, it is possible to perform search and replace operations on the Windows account name in order to derive the user ID from the selected primary user during the issuance. If both options are configured then the prefix or suffix operation will be performed first followed by search and replace operation. Select the AD connection that will be used (already configured from Options - Connections - Active Directory) from the available drop-down list. vSEC:CMS will attempt to find the user in this AD.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the issuance.

For example, if the primary user that would be selected has a Windows account name of:

VERSATILESECURI\adminrole

And in the field Suffix a value of 2 was entered then vSEC:CMS would try to retrieve a Windows account name of:

VERSATILESECURI\adminrole2

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

Generated (Generate ID from UPN)

If this option is selected then it will be possible to configure what prefix or suffix that can be added to a specific Windows UPN. Additionally, it is possible to perform search and replace operations on the Windows UPN in order to derive the user ID from the selected primary user during the issuance. If both options are configured then the prefix or suffix operation will be performed first followed by search and replace operation. Select the AD connection that will be used (already configured from Options - Connections - Active Directory) from the available drop-down list. vSEC:CMS will attempt to find the user in this AD.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the issuance.

For example, if the primary user that would be selected has a Windows UPN of:

adminrole@versasec.com

And in the field Suffix a value of 2 was entered then vSEC:CMS would try to retrieve a Windows UPN of:

adminrole2@versasec.com

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

Select (Manually select user)

If this option is selected then it will be possible to manually select the user during a manual issuance. A manual issuance can be performed from the Actions - Certificate/keys page. This work flow is described below in the section Manually Issue Certificate with Multiple Roles. From the Select user ID using drop-down list the directory that the user will be selected from when manually issuing the certificate for them should be selected.

Click the Save button to save the template.

From variable (ID stored in a variable)

If this option is selected then it will be possible to retrieve the users DN from an attribute value and then use this value to issue a certificate for this user in another directory. Enter a template name in the field available. Select the directory that vSEC:CMS will search for the user in the Verify user ID using drop-down list. Select the variable already configured to point to the directory attribute that stores the users DN from the User ID stored in variable drop-down list.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the issuance.

For example, if the primary user that would be selected has a DN of:

CN=Mary Murphy,CN=Users,DC=VERSATILESECURI,DC=local

then vSEC:CMS would firstly retrieve the DN for the secondary user from the directory attribute value that the variable selected in User ID stored in variable drop-down list retrieves. vSEC:CMS will then search in the directory configured in Verify user ID using drop-down list for this DN.

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

From query (Run LDAP query to retrieve ID)

If this option is selected then it will be possible to retrieve a unique attribute value that can be used to find a user in another directory. Enter a template name in the field available. Select the LDAP directory (you should have one already configured from Options - Connections - LDAP Server) that the query will be performed with to retrieve the unique value that is shared for the user from the Query and verify user ID using drop-down list. Click the Add button to configure the LDAP query.

Enter a template name and enter the base DN by selecting the Get button to automatically retrieve the DNs available or manually entering the actual base DN required in the field. Construct the LDAP filter to define what attribute value should be searched for. For example, if the cn for the user is to be used to retrieve the other Window account(s) for the user then you could have a variable defined as ${CommonName}, as in the example below, that maps to the AD attribute cn. For example, if the primary user account is cn=Joe Bloggs and this user has 2 other Windows account of cn=Joe Bloggs2 and cn=Joe Bloggs3 then an LDAP query (cn=${CommonName}*) could be used where * acts as a wildcard character. Click Ok to save the configuration and close this dialog.

Enable the All vars mandatory if it is required that all variables used in the LDAP query should retrieve a value from the directory.

The Always fail if more than one match found, if enabled, will result in a failed role assignment if the unique attribute has multiple entries for more than one user.

If it is expected that more than one entry will be retrieved, enter the entry that should be used in the Use object from query result field. For example, going back to our example above, the primary user that will be selected is cn=Joe Bloggs and this user has 2 other accounts, then in this case if 1 is set as the value in this field we will retrieve the account cn=Joe Bloggs2 as the user in that case. If you wanted to also get the other account then you would need to create another role attribute and then enter 2 for this field in that template.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the issuance.

For example, if the primary user that would be selected has a DN of:

CN=Sam Flynn,OU=UK, DC=VERSATILESECURI,DC=local

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

Issue Credential Configuration

In this section we will describe by using examples how you can configure a credential template to support multiple roles. We will do this by describing each of the available options with a corresponding simple example.

Configure Using:

1. Generated (Generate ID from distinguished name (DN))

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select Generated (Generate ID from distinguished name (DN)). In this example we will use the user AD attribute CN to retrieve the additional user who we will issue the 2nd credential to. For example, say you have a user whose primary Windows account CN is CN=Tom Smith and his other account has a 2 appended to his CN then enter 2 into the Suffix field. You could then use the Test button and search for the primary user (Tom Smith in this example) and based on the rule the system will attempt to find a user with a CN=Tom Smith2. If it finds one then the system would attempt to issue a credential for that user.

You will need to add the role template as in the example dialog below and click Ok.

In the Enroll Certificate Options section enable the Enroll certificate(s) option and click Add. As this will be the primary certificate credential it is important to select Standard User ID from the User ID drop down field. Select the other options as applicable to your environment and click Ok.

Click the Add button again to configure the second credential that will be added in this example. As this will be the secondary/other role certificate credential, it is important to select Generated ID from DN from the User ID drop down field (as in this example). Select the other options as applicable to your environment and click Ok.

You should see something similar to below after configuration is complete.

Depending on how the credential is issued you should expect to see 2 certificate credentials issued when issuance is completed.

2. Generated (Generate ID from account name (sAMAccountName))

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select Generate ID from account name (sAMAccountName). In User Directory select the AD that we will try to find the user in, i.e. we will try to generate a user DN from the primary user selected from the AD selected in this drop down box. 

In this example we will use the user AD attribute sAMAccountName to retrieve the additional user who we will issue the 2nd credential to. For example, say you have a user whose primary Windows sAMAccountName is Tom and his other account has a 2 appended to his sAMAccountName then enter 2 into the Suffix field. You could then use the Test button and search for the primary user (Tom in this example) and based on the rule the system will attempt to find a user with a sAMAccountName=Tom2. If it finds one then the system would attempt to issue a credential for that user.

You will need to add the role template as in the example dialog below and click Ok.

In the Enroll Certificate Options section enable the Enroll certificate(s) option and click Add. As this will be the primary certificate credential it is important to select Standard User ID from the User ID drop down field. Select the other options as applicable to your environment and click Ok.

Click the Add button again to configure the second credential that will be added in this example. As this will be the secondary/other role certificate credential, it is important to select Generate ID from sAMAccountName from the User ID drop down field (as in this example). Select the other options as applicable to your environment and click Ok.

You should see something similar to below after configuration is complete.

Depending on how the credential is issued you should expect to see 2 certificate credentials issued when issuance is completed.

3. Generated (Generate ID from UPN)

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select Generated (Generate ID from UPN). In User Directory select the AD that we will try to find the user in, i.e. we will try to generate a user DN from the primary user selected from the AD selected in this drop down box.

In this example we will use the user AD attribute userPrincipalName to retrieve the additional user who we will issue the 2nd credential to. For example, say you have a user whose primary Windows userPrincipalName is tom@example.com and his other account has a 2 appended to his userPrincipalName then enter 2 into the Suffix field. You could then use the Test button and search for the primary user (tom@example.com in this example) and based on the rule the system will attempt to find a user with a userPrincipalName=tom2@example.com. If it finds one then the system would attempt to issue a credential for that user.

You will need to add the role template as in the example dialog below and click Ok.

In the Enroll Certificate Options section enable the Enroll certificate(s) option and click Add. As this will be the primary certificate credential it is important to select Standard User ID from the User ID drop down field. Select the other options as applicable to your environment and click Ok.

Click the Add button again to configure the second credential that will be added in this example. As this will be the secondary/other role certificate credential, it is important to select Generate ID from UPN from the User ID drop down field (as in this example). Select the other options as applicable to your environment and click Ok.

You should see something similar to below after configuration is complete.

Depending on how the credential is issued you should expect to see 2 certificate credentials issued when issuance is completed.

4. Select (Manually select user)

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select Select (Manually select user). Select the AD connection to use from the list available in Select user ID using drop-down list.

Click Save to save and close.

You will need to add the role template as in the example dialog below and click Ok.

When it then later comes to actually manually issuing a certificate credential you will need to navigate to Actions - Certificate(s)/Keys and attach an already issued credential. Select the certificate template that should be used from the drop-down list and click Issue.

Then from the dialog that pops up select the manual role template that should be used from the User ID drop-down list. Additionally you will need to select the CA and the certificate template that should be used.

Click Ok and then you will be prompted to select the user from AD that the certificate credential will be issued for. This should complete the flow.

5. From variable (ID stored in a variable)

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select From variable (ID stored in a variable). In Verify user ID using select the AD that we will try to find the user in. In User ID stored in variable select the variable that maps to an AD attribute. This AD attribute will need to contain the DN of the secondary user.  

For example, say you have a user whose primary Windows AD account has an AD attribute called mySecondaryWindowsAccount and this attribute has the DN value of the secondary Windows account for this user. The vSEC:CMS variable is configured to map to this AD attribute. You could then use the Test button and search for the primary user and vSEC:CMS will retrieve the DN value from the attribute and check if the user exists.

You will need to add the role template as in the example dialog below and click Ok.

In the Enroll Certificate Options section enable the Enroll certificate(s) option and click Add. As this will be the primary certificate credential it is important to select Standard User ID from the User ID drop down field. Select the other options as applicable to your environment and click Ok.

Click the Add button again to configure the second credential that will be added in this example. As this will be the secondary/other role certificate credential, it is important to select Generate ID from Variable from the User ID drop down field (as in this example). Select the other options as applicable to your environment and click Ok.

You should see something similar to below after configuration is complete.

Depending on how the credential is issued you should expect to see 2 certificate credentials issued when issuance is completed.

6. From query (Run LDAP query to retrieve ID)

For any template where you wish to use this feature it is necessary to enable Supports multiple role(s) from the General section as in sample dialog below.

Then in the Issue Card section you will see a Role(s) button in the User ID Options section of this dialog. Click this button to configure whatever mechanism you wish to use.

Click the Manage button. Then click the Add button. Enter a name for the template and from the drop-down list select From query (Run LDAP query to retrieve ID). Select the LDAP connection that will be used from Query and verify user ID using and click the Add button to configure the LDAP query.

Enter a template name and enter the base DN by selecting the Get button to automatically retrieve the DNs available or manually entering the actual base DN required in the field. Construct the LDAP filter to define what attribute value should be searched for. For example, if the cn for the user is to be used to retrieve the other Window account(s) for the user then you could have a variable defined as ${CommonName}, as in the example below, that maps to the AD attribute cn. For example, if the primary user account is cn=Joe Bloggs and this user has 2 other Windows account of cn=Joe Bloggs2 and cn=Joe Bloggs3 then an LDAP query (cn=${CommonName}*) could be used where * acts as a wildcard character. Click Ok to save the configuration and close this dialog.

Enable the All vars mandatory if it is required that all variables used in the LDAP query should retrieve a value from the directory.

The Always fail if more than one match found, if enabled, will result in a failed role assignment if the unique attribute has multiple entries for more than one user.

If it is expected that more than one entry will be retrieved, enter the entry that should be used in the Use object from query result field. For example, going back to our example above, the primary user that will be selected is cn=Joe Bloggs and this user has 2 other accounts, then in this case if 1 is set as the value in this field we will retrieve the account cn=Joe Bloggs2 as the user in that case. If you wanted to also get the other account then you would need to create another role attribute and then enter 2 for this field in that template.

It is possible to test the configuration by clicking the Get test ID button and selecting the primary user that would be selected during the issuance.

For example, if the primary user that would be selected has a DN of:

CN=Sam Flynn,OU=UK, DC=VERSATILESECURI,DC=local

Click the Test button and a success dialog will be shown indicating that the settings are correctly configured. Click the Save button to save the template.

You will need to add the role template as in the example dialog below and click Ok.

In the Enroll Certificate Options section enable the Enroll certificate(s) option and click Add. As this will be the primary certificate credential it is important to select Standard User ID from the User ID drop down field. Select the other options as applicable to your environment and click Ok.

Click the Add button again to configure the second credential that will be added in this example. As this will be the secondary/other role certificate credential, it is important to select Generate ID from LDAP Query from the User ID drop down field (as in this example). Select the other options as applicable to your environment and click Ok.

You should see something similar to below after configuration is complete.

Depending on how the credential is issued you should expect to see 2 certificate credentials issued when issuance is completed.

Authenticate Role Accounts During Self-Service Issuance

From version 6.11.2 functionality has been added where you can configure that the user performs a valid authentication for each role they are attempting to issue, when issuance is done via vSEC:CMS User application.

Configure Template

In this section we will describe how you can configure this functionality. We will use a simple example to describe how to configure this. A user has a primary Windows domain account and a secondary privileged Windows domain account. The secondary account in this example will be generated from the primary users UPN.

From Templates - Card Templates click Add. Under General click Edit. Enter a name for the template and attach a blank token that will be used when issuing users and click Detect. Make sure to select the correct reader that the token is attached to and depending on the token type, vSEC:CMS should detect its type. Select Ok to close. Enable Supports multiple role(s) check box. In the Self-service using the following template click the Manage button. Click Add and create a template to meet your requirements. Below is an example that will be used in this case.

Untitled.png

Enable Self-service using the following template check-box and select the template from the drop-down list.

Untitled.png

Leave all other settings as is and click Ok.

Click the Edit link for Issue Card

Click the Roles button and click Manage and Add

Enter a name and select Generated (Generate ID from UPN) from the drop-down list. Select your AD connector from the drop-down list. Next you need to create a rule that will work in your situation. In this example the secondary account will have -admin appended to the users UPN used for the primary account. For example, if the users primary UPN is james@mydomain.com then the expected secondary account UPN would be james-admin@mydomain.com.  You can perform a test in this case to ensure the rule functions as expected. Click the Get test ID button and select the primary user account and click Test.

Untitled.png

Click Save - Close - Add. Select the template just created from Role templates drop-down list and Ok to save and close out.

Untitled.png

Enable Automatically initiate cards after issuance and select Issue by User(s) option. Click the Configure button in the User ID Options section. Select the user directory that the user will be selected from during issuance from the User ID from drop-down list. Select the appropriate authentication method that the user should use from the Authenticate user using drop-down list. Click the Role authentication button. From here you configure the behaviour for authentication when creating the role for this account. There are 3 options:

  1. Disabled: No authentication performed for this role - This means that the user will not be asked to authenticate the different Windows account during issuance.
  2. Enabled: Fail credential issuance when authentication is failing - This means the entire self-service issuance will not be performed, including the primary role, if the authentication step is failing.
  3. Enabled: Skip role enrollment when authentication is failing - This means in cases where the authentication fails for the role(s) then only those role(s) will not be issued. All other role(s) will be issued.

Untitled.png

In the Enroll Certificate Options section enable the Enroll certificate(s) check-box. Click Add. In the User ID drop-down select Standard User ID  which will be used for the primary account that the certificate will be issued to. Select your CA from the Certificate authority drop-down list. In the Certificate template pane select the certificate that is to be issued and click Ok.

Untitled.png

Click Add again. In the User ID drop-down select the role created before, Generate ID from UPN in this example, which will be used for the secondary account that the certificate will be issued to. Select your CA from the Certificate authority drop-down list. In the Certificate template pane select the certificate that is to be issued and click Ok.

Untitled.png

Leave all other settings as is and click Ok - Ok to save and close the template configuration.

Presuming you have already setup self-service in your environment you can now attempt to issue the credential from the vSEC:CMS User application to test the end-to-end flow.

At the start of the self-service issuance you should be prompted to authenticate the 2 different accounts - something like below for example:

Untitled.png

Note
Two limitations exist:
1. Only AD username/password is supported to authenticate the role accounts of the user.
2. The authentication does not take place when performing card template change via card update in self-service where the update includes enrolling certificates for new roles.