Configuring an external identity provider (AD FS)

Checking the AD FS endpoint

You must obtain the OpenID Connect Discovery endpoint (OIDC) or metadata endpoint (SAML) from the server so that you can register AD FS in Common Services.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
Check the necessary endpoint of AD FS.

From the tree on the left side, select AD FS Service Endpoints. From the displayed endpoint information, check the value of URL Path in the row where the Type is "OpenID Connect Discovery" (OIDC) or "Federation Metadata" (SAML).

To obtain the endpoint, simply append the base URI of AD FS to the displayed URL. For example:
- OIDC:
  https://adfs.example.com/adfs/.well-known/openid-configuration
- SAML:
  https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

Registering Common Services in AD FS as an application group

By registering Common Services in AD FS as an application group, you can transfer authentication for the Hitachi Ops Center Portal to AD FS.

Before you begin

The following settings are also necessary for registering AD FS in Common Services and should be determined in advance:

Alias name of AD FS

The alias name is an identifier that uniquely identifies AD FS in Common Services. You can specify up to 64 characters consisting of halfwidth alphabetic characters (lowercase only), numeric characters, hyphens, and underscores. You cannot change the registered value later.
- Example:
  adfs_oidc_ad5
URI of the Web API identifier

The Web API identifier is an identifier that AD FS uses to uniquely identify Common Services. Although you can specify any valid character string, a good practice is to use a name that is easy to identify (such as the host name of the Common Services management server).
- Example:
  https://common_services_host

Procedure

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left side, select AD FS Application Groups. In the pane on the right side, click Application Groups Add Application Group.
In the Welcome window, set the following items, and then click Next:
- Name
  A name of your choice.
- Template
  Select Server application accessing a web API.
In the Server application window, set the following items, and then click Next:
- Client Identifier
  Record this information for when you register AD FS in Common Services.
- Redirect URI
  Specify the host name and port number of the Common Services management server, along with the AD FS alias name:
  https://host-name:port-number/auth/realms/opscenter/broker/alias-name/endpoint
  For alias-name, specify the AD FS alias name that you determined in advance.
In the Configure Application Credentials window, select the Generate a shared secret check box.
Make a note of the Secret, for when you register AD FS in Common Services.
Click Next.
In the Configure Web API window, for Identifier, specify the URI of the Web API identifier that you determined in advance, click Add, and then click Next.
In the Choose Access Control Policy window, specify an access control policy, and then click Next.
In the Configure Application Permissions window, select the following check boxes for Permitted scopes, and then click Next.
- allatclaims
- email
- openid
- profile
In the Summary window, make sure that the settings are correct, and then click Next.
In the Finish window, click Close.

Setting up an issuance transform rule for AD FS

Set up an issuance transform rule for the Common Services instance registered as an application group in AD FS. The login information for the Hitachi Ops Center Portal is transmitted to Common Services is based on these settings.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left, select AD FS Application Groups. In the middle pane, select the application group for Common Services, and then in the right pane, click Properties.
The properties window for the application group appears.
For Applications, select application-group-name- Web API and then click Edit.
The properties window for the Web API appears.
On the Issuance Transform Rules tab, click Add Rule.
The Add Transform Claim Rule Wizard dialog box opens.
On the Select Rule Template window, select Send LDAP Attributes as Claims for Claim rule template, and then click Next.

On the Configure Rule window, set the following items, and then click Finish.

Claim rule name
A name of your choice
Attribute store
Select Active Directory.

Mapping of LDAP attributes to outgoing claim types

Set the following values.

Value to specify for LDAP Attribute	Value to specify for Outgoing Claim Type
Either of the following LDAP attributes for which an email address is registered in the system: User-Principal-Name E-Mail-Addresses	E-Mail Address
Given-Name	Given Name
Surname	Surname
Token-Groups - Qualified by Domain Name	Group

NoteMake sure that the email address, surname, and given name of the Active Directory user for the Hitachi Ops Center Portal are set for the LDAP attributes that you specify. If this information is not set, the user cannot log in.

Verify that the Claim rule has been added to the Issuance Transform Rules tab, and then click OK.

Setting up a claim issuance policy

Set up a claim issuance policy for the Common Services instance registered as a relying party in AD FS. The user attribute information imported when the user logs in to the Hitachi Ops Center Portal is transmitted to Common Services based on the claim issuance policy settings.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left, select AD FS Relying Party Trusts. In the middle pane, select the relying party trust for Common Services, and then in the right pane, click Edit Claim Issuance Policy....
The Edit Claim Issuance Policy dialog box opens.
On the Issuance Transform Rules tab, click Add Rule.
The Add Transform Claim Rule Wizard dialog box opens.
Select Transform an Incoming Claim for the claim rule template, and then click Next.

Specify the following items:

Claim rule name
A name of your choice
Outgoing claim type
The Name ID

Incoming claim type and Outgoing name ID format

Depending on the value specified for NameID Policy Format in Registering AD FS with Common Services, specify the values as follows:

Value specified for NameID Policy Format	Value to specify for Incoming claim type	Value to specify for Outgoing name ID format
Windows Domain Qualified Name	Windows account name	Windows Qualified Domain Name
Email	Either of the following LDAP attributes for which an email address is registered in the system: UPN (User-Principal-Name) E-Mail Address	Email
Unspecified	UPN	UPN

Click Finish.

The claim rule is added to the Edit Claim Issuance Policy dialog box. The values specified here are transmitted to Common Services upon the following claim:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
```
In the Edit Claim Issuance Policy dialog box, click Add Rule again.
The Add Transform Claim Rule Wizard dialog box opens.
Select Send LDAP Attributes as Claims for the claim rule template, and then click Next.

Specify the following items:

Claim rule name
A name of your choice
Attribute Store
Active Directory

Mapping of LDAP attributes to outgoing claim types

Specify values for the following attributes:

LDAP Attribute	Value
Either of the following LDAP attributes for which an email address is registered in the system: User-Principal-Name E-Mail-Addresses	E-Mail Address
Given-Name	Given Name
Surname	Surname
Token-Groups - Qualified by Domain Name	Group

NoteMake sure that the email address, surname, and given name of the Active Directory user who logs in to the Hitachi Ops Center Portal are set for the LDAP attributes that you specify. If this information is not set, the user cannot log in to the Hitachi Ops Center Portal.

Click Finish.

The claim rule is added to the Edit Claim Issuance Policy dialog box. The values specified are transmitted to Common Services through the following claims:

E-Mail Address:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Given Name:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Surname:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Group:
```
http://schemas.xmlsoap.org/claims/Group
```

In the Edit Claim Issuance Policy dialog box, change the order of priority to the following, and then click OK.
1. The rule specified for the Send LDAP Attributes as Claims
2. The rule specified for the Transform an Incoming Claim
To make sure the specified information is correct, select AD FS Service Claim Descriptions.

Registering AD FS with Common Services

You must register AD FS with Common Services as an identity provider.

Log in to the Hitachi Ops Center Portal as sysadmin or a user with opscenter-administrators membership.
From the navigation bar, click Manage users.
In the Users window, from the Asset type, click Identity providers.
In the Identity Providers window, click ＋.

You are prompted to provide the following information (depending on whether you choose the OIDC or SAML protocol):

Item	Value
Provider type	Active Directory Federation Services
Federation protocol	OpenID connect 1.0 (OIDC) or SAML 2.0.
Display name	Name of the identity provider (up to 64 characters).
Alias	Alias name used to uniquely identify the identity provider. Maximum length: 64 characters. Valid character types are half-width alphabetical characters (lowercase only), numbers, hyphens, and underscores. You cannot change this registered value later.
AD FS endpoint metadata URI (SAML only)	Endpoint for importing the AD FS metadata.
OpenID connect discovery endpoint (OIDC only)	Connect Discovery endpoint of AD FS.
Enabled	When Enabled, the Log in using external identity provider link appears in the login window.
Client ID (OIDC only)	Client identifier of AD FS.
Client secret (OIDC only)	Secret name of AD FS.
Web API identifier (OIDC only )	URI of the Web API identifier that was entered for Registering Common Services in AD FS as an application group.
NameID Policy Format (SAML only)	Format for the username when importing the AD FS user as a Common Services local user: Windows Domain Qualified Name (WDQN) Email Unspecified
Allowed clock skew	Acceptable time difference between the management server where Common Services is installed and the AD FS server. If the time difference exceeds this value, you cannot use AD FS to log in. Valid values are 0 to 300 (seconds). Default: 300
Default group mappers	The local group used as the default. (Optional) When AD FS user authentication succeeds, the user is imported into Common Services as a local user. Maximum number of groups is 10.
Custom group mappers	A pair consists of an AD FS group and a local group. (Optional) When AD FS user authentication succeeds, the user is imported into Common Services as a local user. If the user belongs to an AD FS group specified in the Custom group mappers, the corresponding local group is assigned. Maximum number of pairs is 10. You must specify the AD FS group name in the WDQN format, for example: `domain\cs_admin_group`

Identity provider users, group membership, and privileges

When the default group mapper is defined, all users that belong to the external identity provider are assigned to that group when they log in.

By contrast, the custom group mapper requires that each external identity provider user be assigned to the group before they can log in.

External identity provider users are assigned whatever privileges belong to the local group to which they are mapped. For this reason, you should not use the opscenter-administrators as the default group mapper.

An Ops Center administrator can assign group membership individually to identity provider users instead of depending on the group mappers.

Checking the AD FS metadata endpoint

Check the metadata endpoint required to register AD FS in Common Services.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
Check the AD FS metadata endpoints.
From the tree on the left side, select AD FS Service Endpoints. From the displayed endpoint information, check the value of URL Path in the row where the Type is Federation Metadata.
The string obtained by adding the AD FS base URI to the above URL is the AD FS metadata endpoint.
- Example:
  https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml
Make note of the endpoint because you need it for registering AD FS with Common Services.

Registering Common Services in AD FS as a relying party

By registering Common Services in AD FS as a relying party, you can transfer authentication for the Hitachi Ops Center Portal to AD FS.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left side, select AD FS Relying Party Trusts. In the pane on the right side, click Relying Party Trusts Adding Relying Party Trust.
In the Welcome window, select Claims aware, and then click Start.
In the Select Data Source window, select Import data about the relying party from file. For Federation metadata file location, specify the file to which the Common Services metadata was exported, and then click Next.
In the Specifying Display Name window, specify a display name, and then click Next.
In the Choose Access Control Policy window, specify an access control policy, and then click Next.
In the Ready to Add Trust window, make sure that the settings are correct, and then click Next.
In the Finish window, select the Configure claims issuance policy for this application check box, and then click Close.

Setting up a claim issuance policy

Set up a claim issuance policy for the Common Services instance registered as a relying party in AD FS. The user attribute information imported when the user logs in to the Hitachi Ops Center Portal is transmitted to Common Services based on the claim issuance policy settings.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left, select AD FS Relying Party Trusts. In the middle pane, select the relying party trust for Common Services, and then in the right pane, click Edit Claim Issuance Policy....
The Edit Claim Issuance Policy dialog box opens.
On the Issuance Transform Rules tab, click Add Rule.
The Add Transform Claim Rule Wizard dialog box opens.
Select Transform an Incoming Claim for the claim rule template, and then click Next.

Specify the following items:

Claim rule name
A name of your choice
Outgoing claim type
The Name ID

Incoming claim type and Outgoing name ID format

Depending on the value specified for NameID Policy Format in Registering AD FS with Common Services, specify the values as follows:

Value specified for NameID Policy Format	Value to specify for Incoming claim type	Value to specify for Outgoing name ID format
Windows Domain Qualified Name	Windows account name	Windows Qualified Domain Name
Email	Either of the following LDAP attributes for which an email address is registered in the system: UPN (User-Principal-Name) E-Mail Address	Email
Unspecified	UPN	UPN

Click Finish.

The claim rule is added to the Edit Claim Issuance Policy dialog box. The values specified here are transmitted to Common Services upon the following claim:
```
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
```
In the Edit Claim Issuance Policy dialog box, click Add Rule again.
The Add Transform Claim Rule Wizard dialog box opens.
Select Send LDAP Attributes as Claims for the claim rule template, and then click Next.

Specify the following items:

Claim rule name
A name of your choice
Attribute Store
Active Directory

Mapping of LDAP attributes to outgoing claim types

Specify values for the following attributes:

LDAP Attribute	Value
Either of the following LDAP attributes for which an email address is registered in the system: User-Principal-Name E-Mail-Addresses	E-Mail Address
Given-Name	Given Name
Surname	Surname
Token-Groups - Qualified by Domain Name	Group

NoteMake sure that the email address, surname, and given name of the Active Directory user who logs in to the Hitachi Ops Center Portal are set for the LDAP attributes that you specify. If this information is not set, the user cannot log in to the Hitachi Ops Center Portal.

Click Finish.

The claim rule is added to the Edit Claim Issuance Policy dialog box. The values specified are transmitted to Common Services through the following claims:

E-Mail Address:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Given Name:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

Surname:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Group:
```
http://schemas.xmlsoap.org/claims/Group
```

In the Edit Claim Issuance Policy dialog box, change the order of priority to the following, and then click OK.
1. The rule specified for the Send LDAP Attributes as Claims
2. The rule specified for the Transform an Incoming Claim
To make sure the specified information is correct, select AD FS Service Claim Descriptions.

Exporting Common Services metadata

To link with AD FS, you must register Common Services metadata into AD FS. From the Hitachi Ops Center Portal, output the metadata to a file and then send the file to the AD FS server.

Procedure

Log in to the Hitachi Ops Center Portal as the sysadmin user or as a user who is a member of the opscenter-administrators group.
In the navigation bar, click Manage users.
In Asset type in the Users window, click Identity providers.
In the Identity Providers window, click the target AD FS.
In the Identity provider details window, click Download metadata.
The Common Services metadata file is downloaded. Transfer this file to the AD FS server.

Updating an identity provider configuration

Procedure

Log in to the Hitachi Ops Center Portal as sysadmin or a user with opscenter-administrators membership.
From the navigation bar, click Manage users.
In the Users window, from the Asset type, click Identity providers.
Click the edit icon (pencil) for the identity provider.
Update the information and then click Next to proceed through all the entry windows.
Click Submit when you reach the last window and your changes are complete.

Updating the authentication certificates used with an identity provider (SAML)

This section explains how to check the date of the next update of a certificate, manually update a certificate, and change the number of days set as the update interval of the Common Services authentication key and AD FS Token certificates that are used with an identity provider.

If you link with an identity provider by using the OIDC protocol, you do not need to perform this procedure.

Understanding certificate updates

Identity providers use two types of authentication certificates:

Common Services certificates (known as authentication keys)
AD FS certificates (Token certificates)

Both have an expiration date and are automatically updated according to a defined interval (in days).

However, when this update occurs, a discrepancy arises between the new certificate and the previously registered certificate. For this reason, users can no longer log in to the Ops Center portal using the identity provider link. To prevent this problem, you must keep track of when the next update will occur and update the certificate manually before it expires.

NoteWhen you log in using the identity provider, the Ops Center portal displays a reminder when the certificate is due to expire within 30 days.

If it is inconvenient to update the Common Services authentication key immediately, you can suppress the update by temporarily increasing the update interval. (Although you can also change the update interval of AD FS Token certificates, this only applies to the next update.)

TipFor best results, specify the same update interval for the Common Services authentication key and the AD FS Token certificates. This enables you to update both on the same day. You should also consider perform the update during off-hours (when no users are logged in).

Checking the next update for the Common Services certificates

Check the date of the next update of the authentication key for Common Services.

Log in to the Hitachi Ops Center Portal as the sysadmin user or as a user who is a member of the opscenter-administrators group.

NoteIf the date of the next update of the authentication key will occur within 30 days, a message to that effect is displayed when you log in.
Select Settings Authentication key, and then check the value displayed for Authentication key next update date (UTC).

Checking the dates of the next update of the AD FS certificates

Check the dates of the next update of the Token certificates of AD FS.

Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left side, select AD FS Service Certificates.
Check the value of Expiration Date for Token-decrypting and Token-signing in the middle pane.

Updating the Common Services certificates

If the date of the next update of the authentication key of Common Services is approaching, update the authentication key and the metadata. You can also change the update interval of the authentication key without actually updating the key.

Log in to the Hitachi Ops Center Portal as the sysadmin user or as a user who is a member of the opscenter-administrators group.
Select Settings Authentication key.
The Authentication key window appears.
To change the update interval of the authentication key, change the value of Authentication Key update interval (days).

The default value is 180 days (with a range of 90 to 3,650). From a security standpoint, we recommend 90-180 days.
For Update Authentication key now, select Yes.
If you want to change the update interval without updating the authentication key, select No.
Click Submit.
If you selected No for Update Authentication key now, skip the remaining.
Export the metadata of Common Services. For details, see Exporting Common Services metadata.
Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left side, select AD FS Relying Party Trusts.
In Relying Party Trusts, check the value of Identifier for the Common Services instance that is registered.

Run the following command in PowerShell:

Update-AdfsRelyingPartyTrust -MetadataFile storage-location-of-the-metadata-file -TargetIdentifier ID-of-the-relying-party

For ID-of-the-relying-party, specify the value of Identifier for Common Services (checked in the previous step).

Example of running the command:

Update-AdfsRelyingPartyTrust -MetadataFile metadata.xml -TargetIdentifier https://www.example.com:8443/auth/realms/opscenter

For details on the command, see the AD FS documentation.

Updating the AD FS certificates

Run the AD FS command Update-AdfsCertificate to update the Token certificates. After updating the certificates, you must specify the metadata endpoint for AD FS from the Hitachi Ops Center Portal, and then update the information about AD FS registered in Common Services.

NoteFor details about Token certificates and the command, see the AD FS documentation.

Procedure

Log in to the AD FS server.
To change the update interval of Token certificates, run the following command in PowerShell.
```
Set-AdfsProperties -CertificateDuration update-interval-(number-of-days)
```
The change will take effect the next time the Token certificates are updated after you change the update interval.
- Example of 3 years:
```
Set-AdfsProperties -CertificateDuration 1095
```

To make the change take effect immediately, run the following command in PowerShell to update the Token certificates.

Update-AdfsCertificate -CertificateType Token-Decrypting -Urgent
Update-AdfsCertificate -CertificateType Token-Signing -Urgent

Log in to the Hitachi Ops Center Portal as sysadmin or a user with opscenter-administrators membership.
In the navigation bar, click Manage users.
In Asset type in the Users window, click Identity providers.
Click the Edit identity provider icon for the registered identify provider.
For AD FS endpoint metadata URI, set the metadata endpoint for AD FS.
For details on how to check the metadata endpoint, see Checking the AD FS endpoint.
Click Next without changing any other values.
In the Edit identity provider - confirmation window, click Submit.

If you cannot sign on with an identity provider

If you cannot sign on using an identity provider, there are two possibilities:

Certificates for Common Services were updated.
In this scenario, if you cannot log in using an identity provider, the following message is output to Applications and Services Logs AD FS Admin in the AD FS event log:
ID6013: The signature verification failed
For details on what to do when this message is output, see Updating the Common Services metadata by using AD FS.
Certificates for AD FS were updated.
In this scenario, if you cannot log in using an identity provider, the following message is output Common Services log file (default: /var/log/hitachi/CommonService/idp/log/server.log) :
ERROR [org.keycloak.broker.saml.SAMLEndpoint] (default task-14) validation failed
For details on what to do when this message is output, see Specifying the AD FS metadata endpoint by using Common Services.

Updating the Common Services metadata by using AD FS

You can update the Common Services metadata by using AD FS.

Procedure

Export the metadata of Common Services. For details, see Exporting Common Services metadata.
Log in to the AD FS server.
Select Start Windows Administrative Tools AD FS Management.
From the tree on the left side, select AD FS Relying Party Trusts.
In Relying Party Trusts, check the value of Identifier for the Common Services instance that is registered.

Run the following command in PowerShell:

Update-AdfsRelyingPartyTrust -MetadataFile storage-location-of-the-metadata-file -TargetIdentifier ID-of-the-relying-party

For ID-of-the-relying-party, specify the value of Identifier for Common Services (checked in the previous step).

Example:

Update-AdfsRelyingPartyTrust -MetadataFile metadata.xml -TargetIdentifier https://www.example.com:8443/auth/realms/opscenter

For details on the command, see the AD FS documentation.

Specifying the AD FS metadata endpoint by using Common Services

You can specify the AD FS metadata endpoint by using Common Services.

Procedure

Log in to the Hitachi Ops Center Portal as the sysadmin user or as a user who is a member of the opscenter-administrators group.
In the navigation bar, click Manage users.
In Asset type in the Users window, click Identity providers.
Click the Edit identity provider icon for the registered identity provider.
For AD FS endpoint metadata URI, set the metadata endpoint for AD FS.
For details on how to check the metadata endpoint, see Checking the AD FS metadata endpoint.
Click Next without changing any other values.
In the Edit identity provider - confirmation window, click Submit.

Removing an identity provider

You can remove an identity provider from Ops Center.

Procedure

Log in to the Hitachi Ops Center Portal as sysadmin or a user with opscenter-administrators membership.
From the navigation bar, click Manage users.
In the Users window, from the Asset type, click Identity providers.
Click the delete icon (trash can) for the identity provider.
Click Submit in the Delete dialog box.

Quick Links

Checking the AD FS endpoint

Registering Common Services in AD FS as an application group

Setting up an issuance transform rule for AD FS

Setting up a claim issuance policy

Registering AD FS with Common Services

Identity provider users, group membership, and privileges

Checking the AD FS metadata endpoint

Registering Common Services in AD FS as a relying party

Setting up a claim issuance policy

Exporting Common Services metadata

Updating an identity provider configuration

Updating the authentication certificates used with an identity provider (SAML)

Understanding certificate updates

Checking the next update for the Common Services certificates

Checking the dates of the next update of the AD FS certificates

Updating the Common Services certificates

Updating the AD FS certificates

If you cannot sign on with an identity provider

Updating the Common Services metadata by using AD FS

Specifying the AD FS metadata endpoint by using Common Services

Removing an identity provider