3 Administrator Account Management

This chapter explains how the default administrator creates additional administrator accounts, and how the Service Enclave provides control over administrator account privileges, preferences and passwords.

Technical background information can be found in the Oracle Private Cloud Appliance Concepts Guide. Refer to the section "Administrator Access" in the chapter "Appliance Administration Overview".

Creating a New Administrator Account

During system initialization, a default administrator account is set up. This default account cannot be deleted. It provides access to the Service Enclave, from where additional administrator accounts can be created and managed.

Using the Service Web UI

  1. Open the navigation menu and click Users.

  2. Click Create User to open the Create User window.

  3. Enter the following details:

    • Name: Enter a name for this administrator account. This is the name that will be used to log in.

    • Authorization Group: Select the authorization group to which the new administrator is added. This selection determines the access rights and privileges of the administrator account.

    • Password: Set a password for the new administrator account. Enter it a second time to confirm.

  4. Click Create User. The new administrator account is displayed in the Users table.

Using the Service CLI

  1. Display the list of authorization groups. Copy the ID of the authorization group in which you want to create the new administrator account.

    PCA-ADMIN> list AuthorizationGroup
    Command: list AuthorizationGroup
    Status: Success
    Time: 2021-08-25 08:38:58,632 UTC
    Data:
      id                                     name
      --                                     ----
      587fc90d-3312-41d9-8be3-1ce21b8d9b41   MonitorGroup
      c18cc6af-4ef8-4b1c-b85d-ee3b065f503e   DrAdminGroup
      8f03faf2-c321-4455-af21-75cbffc269ef   AdminGroup
      5ac65f5d-1f8c-42ea-a1de-95a1941f009f   Day0ConfigGroup
      365ece7b-0a09-4a04-853c-7a0f6c4789f0   InternalGroup
      7da8be67-758c-4cd6-8255-e9d2900c788e   SuperAdminGroup
  2. Create a new administrator account using the command createUserInGroup.

    Required parameters are the user name, password and authorization group.

    PCA-ADMIN> createUserInGroup name=testadmin password=************ confirmPassword=************ authGroup=365ece7b-0a09-4a04-853c-7a0f6c4789f0
    Command: createUserInGroup name=testadmin password=***** confirmPassword=***** authGroup=365ece7b-0a09-4a04-853c-7a0f6c4789f0
    Status: Success
    Time: 2021-08-25 08:48:53,138 UTC
    JobId: 6dd5a542-4399-4414-ac3b-636968744f79
  3. Verify that the new administrator account was created correctly. Use the list and show commands to display the account information.

    PCA-ADMIN> list User
    Command: list User
    Status: Success
    Time: 2021-08-25 08:49:01,064 UTC
    Data:
      id                                     name
      --                                     ----
      401fce73-5bee-48b1-b86d-fba1d85e049b   admin
      682ebc19-8493-4e9a-817c-148acea4b1d4   testadmin
    
    PCA-ADMIN> show user name=testadmin
    Command: show User name=testadmin
    Status: Success
    Time: 2021-08-25 08:50:04,245 UTC
    Data:
      Id = 682ebc19-8493-4e9a-817c-148acea4b1d4
      Type = User
      Name = testadmin
      Default User = false
      AuthGroupIds 1 = id:365ece7b-0a09-4a04-853c-7a0f6c4789f0  type:AuthorizationGroup  name:InternalGroup
      UserPreferenceId = id:1321249c-0651-49dc-938d-7764b9638ea9  type:UserPreference  name:

Changing Administrator Credentials

The administrator's password is set during account creation. You can always change the password for your own account. Depending on privileges, you may be authorized to change the password of another administrator as well.

Using the Service Web UI

  1. Open the navigation menu and click Users.

  2. Click the administrator account for which you want to change the password. The user detail page is displayed.

    Alternatively, to display your own user detail page, click your name in the top-right corner of the page and select My Profile.

  3. Click Change Password to open the Change Password window.

  4. Enter the new account password. Enter it a second time for confirmation. Click Save Changes to apply the new password.

Using the Service CLI

  1. Display the list of administrator accounts. Copy the ID of the account for which you want to change the password.

    PCA-ADMIN> list User
    Command: list User
    Status: Success
    Time: 2021-08-25 09:22:01,064 UTC
    Data:
      id                                     name
      --                                     ----
      401fce73-5bee-48b1-b86d-fba1d85e049b   admin
      682ebc19-8493-4e9a-817c-148acea4b1d4   testadmin
  2. Set a new password for the selected administrator account using the changePassword command.

    PCA-ADMIN> changePassword id=682ebc19-8493-4e9a-817c-148acea4b1d4 password=************ confirmPassword=************
    Command: changePassword id=682ebc19-8493-4e9a-817c-148acea4b1d4 password=***** confirmPassword=*****
    Status: Success
    Time: 2021-08-25 09:22:55,188 UTC
    JobId: 35710cd9-26ac-4be9-8b73-c4cf634cc121

Managing Administrator Privileges

An administrator is granted privileges through his membership in an authorization group or groups. When you create an administrator account, you select the authorization group to which the new administrator is added. However, you can change which authorization groups an administrator belongs to at any time.

For more information, see "Administrator Access" in the Appliance Administration Overview section of the Oracle Private Cloud Appliance Concepts Guide.

Using the Service Web UI

To add an administrator to an additional authorization group:

  1. Open the navigation menu and click Authorization Groups.

  2. Click the authorization group to which you want to add an administrator.

  3. Under Resources, click Users and then click Add User to Group.

  4. From the Add User to Group form, select an administrator and then click OK.

Before you can remove an adminsitrator from an authorization group, you must make sure he belongs to at least one other group. To remove an administrator from an authorization group:

  1. If the administrator belongs only to the authorization group you want to remove him from, add the administrator to another authorization group

    .
  2. Open the navigation menu and click Authorization Groups.

  3. Click the authorization group for which you want to remove an administrator.

  4. Under Resources, click Users. The list of users in the authorization group is displayed.

  5. From the list, click the Actions menu for the user you want to remove and then click Remove User from Group.

Using the Service CLI

  1. Gather the IDs of the administrator account you want to change, and the authorization groups involved in the configuration change.

    PCA-ADMIN> list User
    Command: list User
    Status: Success
    Time: 2021-08-25 09:22:01,064 UTC
    Data:
      id                                     name
      --                                     ----
      401fce73-5bee-48b1-b86d-fba1d85e049b   admin
      682ebc19-8493-4e9a-817c-148acea4b1d4   testadmin
    
    PCA-ADMIN> list AuthorizationGroup
    Command: list AuthorizationGroup
    Status: Success
    Time: 2021-08-25 08:38:58,632 UTC
    Data:
      id                                     name
      --                                     ----
      587fc90d-3312-41d9-8be3-1ce21b8d9b41   MonitorGroup
      c18cc6af-4ef8-4b1c-b85d-ee3b065f503e   DrAdminGroup
      8f03faf2-c321-4455-af21-75cbffc269ef   AdminGroup
      5ac65f5d-1f8c-42ea-a1de-95a1941f009f   Day0ConfigGroup
      365ece7b-0a09-4a04-853c-7a0f6c4789f0   InitialGroup
      7da8be67-758c-4cd6-8255-e9d2900c788e   SuperAdminGroup
  2. To add an administrator to an authorization group, use the add User command.

    PCA-ADMIN> add User id=682ebc19-8493-4e9a-817c-148acea4b1d4 to AuthorizationGroup id=587fc90d-3312-41d9-8be3-1ce21b8d9b41
    Command: add User id=682ebc19-8493-4e9a-817c-148acea4b1d4 to AuthorizationGroup id=587fc90d-3312-41d9-8be3-1ce21b8d9b41
    Status: Success
    Time: 2021-08-25 08:49:54,062 UTC
    JobId: 3facde6d-acb6-4fc4-84dc-93de88eea25c
  3. Display the administrator account details to verify the changes you made.

    PCA-ADMIN> show User name=testadmin
    Command: show User name=testadmin
    Status: Success
    Time: 2021-08-25 08:50:04,245 UTC
    Data:
      Id = 682ebc19-8493-4e9a-817c-148acea4b1d4
      Type = User
      Name = testadmin
      Default User = false
      AuthGroupIds 1 = id:365ece7b-0a09-4a04-853c-7a0f6c4789f0  type:AuthorizationGroup  name:InternalGroup
      AuthGroupIds 2 = id:587fc90d-3312-41d9-8be3-1ce21b8d9b41  type:AuthorizationGroup  name:MonitorGroup
      UserPreferenceId = id:1321249c-0651-49dc-938d-7764b9638ea9  type:UserPreference  name:
  4. To remove an administrator from an authorization group, use the remove User command.

    PCA-ADMIN> remove User name=testadmin from AuthorizationGroup id=587fc90d-3312-41d9-8be3-1ce21b8d9b41
    Command: remove User name=testadmin from AuthorizationGroup id=587fc90d-3312-41d9-8be3-1ce21b8d9b41
    Status: Success
    Time: 2021-08-25 09:10:39,249 UTC
    JobId: 44110d28-70af-4a42-8eb7-7d59a3bc8295

Working with Authorization Groups

As an administrator, the specific functions you can perform is dependent on the authorization group to which you belong. Every authorization group must have at least one attached policy statement that allows users who belong to this group access to resources. An authorization group without a policy statement is valid, but its users would not have access to any resources.

You can create the policy statements immediately after you create the authorization group or you can add policy statements later. You can also list or delete policy statements using both the Service Web UI and Service CLI. Additionally, you can inactivate a policy statement using the Service CLI.

Note:

You cannot modify a policy statement. If you need to make changes to a policy statement, you must delete it and then recreate it.

For more information, see "Administrator Access" in the Appliance Administration Overview section of the Oracle Private Cloud Appliance Concepts Guide.

Using the Service Web UI

  1. Open the navigation menu and click Authorization Group.

  2. Click Create Group.

  3. Enter a name using 1 to 255 characters, and then click Create Authorization Group.

    The new authorization group's details page displays.

  4. Click Add Policy Statement. The Authorization Policy Statement Form window displays.
  5. Enter a name using 1 to 255 characters.
  6. Select an action: Inspect, Read, Use, or Manage.
  7. Select a policy application:
    • Resources - Enter the resources you want the policy to apply to.
    • Function Family - Select one from the drop down.
    • Resource Family - Select one from the drop down.

    Note:

    For information on how to find the resource and function options, see the Using the Service CLI section.
  8. Click Create Policy Statement.

    The new policy statement displays on the details page. Add up to 100 additional policy statements.

Using the Service CLI

  1. Create a new authorization group.

    PCA-ADMIN> create AuthorizationGroup name=authors
    Status: Success
    Time: 2022-05-22 13:10:12,463 UTC
    JobId: 14ea4d22-acf1-455d-a7a1-ec0a30f29671
    Data:
    id:c672d9c6-90ec-4776-bccb-caae128e86db name:authors
  2. View the help for the create authpolicyStatement command.
    PCA-ADMIN> create authpolicyStatement ?
    *action
    activeState
    functionFamily
    resourceFamily
    resources
    *on
  3. Enter showcustomcmds ? to see options for resources, or enter showallcustomcmds to view options for functions, for example:
    PCA-ADMIN> showcustomcmds ?
                              ASRBundle
                              ASRPhonehome
                              BackupJob
                              CnUpdateManager
                              ComputeInstance
                              ComputeNode
                              [...]
    
    PCA-ADMIN> showallcustomcmds
        Operation Name: <Related Object(s)>
        -----------------------------------
        [...]
        backup:  BackupJob
        changeIlomPassword:  ComputeNode, ManagementNode
        changePassword:  ComputeNode, LeafSwitch, ManagementNode, ManagementSwitch, SpineSwitch, User, ZFSAppliance
        clearFirstBootError:  NetworkConfig
        configZFSAdDomain:  ZfsAdDomain
        configZFSAdWorkgroup:  ZfsAdDomain
        createAdminAccount:  
        createUserInGroup:  User
        deletePlatformImage:  PlatformImage
        deprovision:  ComputeNode
        disableVmHighAvailability:  PcaSystem
        drAddComputeInstance:  ComputeInstance
        drAddSiteMapping:  DrSiteMapping
        [...]

    Note:

    For more information on resources and functions, see Command Syntax and Base and Custom Commands.
  4. Create a policy statement using resources, functionFamily or resourceFamily.

    PCA-ADMIN> create authpolicyStatement action=manage resources=ComputeNode on authorizationGroup id=c672d9c6-90ec-4776-bccb-caae128e86db
    PCA-ADMIN> create authpolicyStatement action=manage authresourceFamily=rackops on authorizationGroup id=c672d9c6-90ec-4776-bccb-caae128e86db
    PCA-ADMIN> create authpolicyStatement action=manage authfunctionFamily=computeops on authorizationGroup id=c672d9c6-90ec-4776-bccb-caae128e86db
  5. View the details for the authorization group.
    PCA-ADMIN> show authorizationGroup name=authors
    Command: show authorizationGroup name=authors
    Status: Success
    Time: 2022-05-23 11:32:42,335 UTC
    Data:
    Id = c672d9c6-90ec-4776-bccb-caae128e86db
    Type = AuthorizationGroup
    Name = authors
    Policy Statements 1 = dea601bf-9bfc-4b2c-a135-d98378e69c87(ACTIVE)-Allow authors to MANAGE ComputeNode
    Is Predefined Authorization Group = false
    AuthPolicyStatementIds 1 = id:4adde579-1f6a-49eb-a783-9478465f135e type:AuthPolicyStatement name:
    AuthPolicyStatementIds 2 = id:be498a4e-3e0a-4cfa-9013-188542adb8e3 type:AuthPolicyStatement name:

To inactivate a policy statement:

  1. View the help for the edit authpolicyStatement command.
    PCA-ADMIN> edit authpolicyStatement ?
    id=<object identifier>
  2. Find the policy statement's ID using the show authorizationGroup name=group-name command.
    PCA-ADMIN> show authorizationGroup name=authors
    Command: show authorizationGroup name=authors
    […]
    Policy Statements 1 = dea601bf-9bfc-4b2c-a135-d98378e69c87(ACTIVE)-Allow authors to MANAGE ComputeNode
    Is Predefined Authorization Group = false
    AuthPolicyStatementIds 1 = id:4adde579-1f6a-49eb-a783-9478465f135e type:AuthPolicyStatement name:
    AuthPolicyStatementIds 2 = id:be498a4e-3e0a-4cfa-9013-188542adb8e3 type:AuthPolicyStatement name:
  3. Using the ID of the policy statement (AuthPolicyStatementIds Number = id:unique-identifier) view the command to activate or inactivate the policy statement.
    PCA-ADMIN> edit authpolicyStatement id=be498a4e-3e0a-4cfa-9013-188542adb8e3 ?
    activeState
    
  4. Inactivate the policy statement.
    PCA-ADMIN> edit authpolicyStatement id=be498a4e-3e0a-4cfa-9013-188542adb8e3 activeState=inactive
    Command: edit authpolicyStatement id=be498a4e-3e0a-4cfa-9013-188542adb8e3 activeState=inactive
    Status: Success
    Time: 2022-05-23 11:42:11,446 UTC
    JobId: 842c444e-060d-461d-a4e0-c9cdd9f1d3c3
  5. Verify the policy statement is inactive.
    PCA-ADMIN> show authorizationGroup name=authors
    Command: show authorizationGroup name=authors
    Status: Success
    Time: 2022-05-23 11:42:26,995 UTC
    Data:
    Id = c672d9c6-90ec-4776-bccb-caae128e86db
    Type = AuthorizationGroup
    Name = authors
    Policy Statements 1 = 4adde579-1f6a-49eb-a783-9478465f135e(ACTIVE)-Allow authors to MANAGE ComputeNode
    Policy Statements 2 = be498a4e-3e0a-4cfa-9013-188542adb8e3(INACTIVE)-Allow authors to MANAGE ComputeNode
    Is Predefined Authorization Group = false
    AuthPolicyStatementIds 1 = id:4adde579-1f6a-49eb-a783-9478465f135e type:AuthPolicyStatement name:
    AuthPolicyStatementIds 2 = id:be498a4e-3e0a-4cfa-9013-188542adb8e3 type:AuthPolicyStatement name:

Working with Authorization Families

Authorization families allow you to group resources and functions that make logical sense in the management of your appliance. There are two types of authorization families you can use in policy statements: Function Family and Resource Family.

For more information on resources and functions, see Command Syntax and Base and Custom Commands.

For conceptual information on authorization groups, policies, and families, see "Administrator Access" in the Oracle Private Cloud Appliance Concepts Guide.

Using the Service Web UI

  1. Open the navigation menu and click Authorization Families.

  2. Click Create Authorization Family.

  3. Select either authorization family type: Function Family or Resources Family.

  4. Enter a name.

  5. Enter the resources to include in the family.

    Note:

    For information on how to find the resource and function options, see the Using the Service CLI section.
  6. Click Create Family.

Using the Service CLI

Create an authorization function family.
  1. Display the options for the create authfunctionFamily command.

    PCA-ADMIN> create authfunctionFamily ?
    *name
    *resources
  2. Enter showallcustomcmds to view options for functions, for example:
    PCA-ADMIN> showallcustomcmds
        Operation Name: <Related Object(s)>
        -----------------------------------
        [...]
        backup:  BackupJob
        changeIlomPassword:  ComputeNode, ManagementNode
        changePassword:  ComputeNode, LeafSwitch, ManagementNode, ManagementSwitch, SpineSwitch, User, ZFSAppliance
        clearFirstBootError:  NetworkConfig
        configZFSAdDomain:  ZfsAdDomain
        configZFSAdWorkgroup:  ZfsAdDomain
        createAdminAccount:  
        createUserInGroup:  User
        deletePlatformImage:  PlatformImage
        deprovision:  ComputeNode
        disableVmHighAvailability:  PcaSystem
        drAddComputeInstance:  ComputeInstance
        drAddSiteMapping:  DrSiteMapping
        [...]
  3. Create the authorization function family.
    PCA-ADMIN> create authfunctionFamily name=cnops resources=ComputeNode.reset,ComputeNode.start,ComputeNode.stop
    Command: create authfunctionFamily name=cnops resources=ComputeNode.reset,ComputeNode.start,ComputeNode.stop
    Status: Success
    Time: 2022-05-23 12:29:40,651 UTC
    JobId: 4cd37ea7-161f-4b11-952f-ffa992a37d5f
    Data:
    id:ae0216da-20d1-4e03-bf65-c7898c6079b2 name:cnops
  4. List the authorization function families.
    PCA-ADMIN> list authfunctionFamily
    Command: list authfunctionFamily
    Status: Success
    Time: 2022-05-23 12:29:57,164 UTC
    Data:
    id name
    -- ----
    7f1ac922-571a-4253-a120-e5d15a877a1e Initial
    2185058a-3355-48be-851c-2fa0e5a896bd SuperAdmin
    7f092ddd-1a51-4a17-b4e2-96c4ece005ec Day0
    ae0216da-20d1-4e03-bf65-c7898c6079b2 cnops

Create an authorization resource family.

  1. Display the options for the create authresourceFamily command.

    PCA-ADMIN> create authresourceFamily ?
    *name
    *resources
  2. Enter showcustomcmds ? to see options for resources, for example:
    PCA-ADMIN> showcustomcmds ?
                              ASRBundle
                              ASRPhonehome
                              BackupJob
                              CnUpdateManager
                              ComputeInstance
                              ComputeNode
                              [...]

    Note:

    For more information on resources and functions, see Command Syntax and Base and Custom Commands.
  3. Create the authorization resource family.
    PCA-ADMIN> create authresourceFamily name=rackops resources=ComputeNode,RackUnit
    Command: create authresourceFamily name=rackops resources=ComputeNode,RackUnit
    Status: Success
    Time: 2022-05-23 11:52:37,751 UTC
    JobId: eb49ac48-e3f3-4c2f-bf11-d5d18a066788
    Data:
    id:b54e4413-15bd-440e-b399-e2ab75f17c35 name:rackops
  4. List the authorization resource families.
    PCA-ADMIN> list authresourceFamily
    Command: list authresourceFamily
    Status: Success
    Time: 2022-05-23 11:57:37,464 UTC
    Data:
    id name
    -- ----
    9aefc9c8-556d-42a4-9369-d7cdf0bf0c52 SuperAdmin
    b591cc7b-b117-449e-af35-cb4fc6f0c213 Day0
    87633db2-d724-45b6-97a5-30babb6c4869 cnops
    b54e4413-15bd-440e-b399-e2ab75f17c35 rackops
    a45c08b4-f895-4da8-87f4-c81ca0b2bf27 Initial

Changing Administrator Account Preferences

When logged in to the Service CLI you can change certain settings for your own administrator account. Those changes take effect immediately and are persisted for all your future CLI connections.

However, you can also change settings temporarily for just your current CLI session. To do so, replace the object UserPreference with CliSession in the command examples below.

Setting Options Description

alphabetizeMode

YES, NO

Enable this setting to display any managed object's attributes in alphabetical order. The default setting is "No".

attributeDisplay

DISPLAYNAME, ATTRIBUTENAME

Use this setting to control whether the name of each object's attribute is displayed. The default setting is "displayName".

endLineCharsDisplayValue

CRLF, CR, LF

Specify the end-of-line character to be used when the CLI output consists of multiple lines. The default setting is "CRLF".

outputMode

VERBOSE, SPARSE, XML

Specify the CLI output format. The default setting is "Sparse".

wsCallMode

SYNCHRONOUS, ASYNCHRONOUS

Use this setting to determine whether the CLI output from a command is invoked synchronously or asynchronously. The default setting is "Asynchronous".

wsTimeoutInSeconds

<value>

When the CLI is set to "Synchronous" call mode, use this setting to determine how many seconds the CLI waits for a job returned by an operation to complete.

Using the Service CLI

  1. Display your current account preferences.

    PCA-ADMIN> show UserPreference
    Command: show UserPreference
    Status: Success
    Time: 2021-08-25 12:23:41,265 UTC
    Data:
      Id = ec433c0f-4208-4e92-859e-498218d0f5c9
      Type = UserPreference
      WS Call Mode = Asynchronous
      Alphabetize Mode = No
      Attribute Display = Display Name
      End Line Characters Display Value = CRLF
      Output Mode = Verbose
      Command Wait Timeout In Seconds = 240
      UserId = id:401fce73-5bee-48b1-b86d-fba1d85e049b  type:User  name:admin
  2. Change the setting of your choice using the edit userPreference command.

    PCA-ADMIN> edit UserPreference outputMode=XML
    Command: edit UserPreference outputMode=XML
    Status: Success
    Time: 2021-08-25 12:32:02,102 UTC
    JobId: 9d312d9b-6169-47cb-97d4-6a8984237fa0
  3. Execute the same command for any other settings you wish to change.

  4. Display your current account preferences again to verify the changes you made.

    PCA-ADMIN> show UserPreference
    Command: show UserPreference
    Status: Success
    Time: 2021-08-25 12:32:40,664 UTC
    Data:
      Id = ec433c0f-4208-4e92-859e-498218d0f5c9
      Type = UserPreference
      WS Call Mode = Asynchronous
      Alphabetize Mode = No
      Attribute Display = Display Name
      End Line Characters Display Value = CRLF
      Output Mode = Xml
      Command Wait Timeout In Seconds = 180
      UserId = id:401fce73-5bee-48b1-b86d-fba1d85e049b  type:User  name:admin

Deleting an Administrator Account

This section describes how to delete an administrator account.

Using the Service Web UI

  1. Open the navigation menu and click Users.

  2. Click the administrator account you want to delete. The user detail page is displayed.

  3. Click Delete. Confirm the operation when prompted.

Using the Service CLI

  1. Look up the name and ID of the administrator account you want to delete.

    PCA-ADMIN> list User
    Command: list User
    Status: Success
    Time: 2021-08-25 08:49:01,064 UTC
    Data:
      id                                     name
      --                                     ----
      401fce73-5bee-48b1-b86d-fba1d85e049b   admin
      682ebc19-8493-4e9a-817c-148acea4b1d4   testadmin
  2. To delete the administrator account, use the delete User command followed by the account name or ID.

    PCA-ADMIN> delete User name=testadmin
    Command: delete user name=testadmin
    Status: Success
    Time: 2021-08-25 09:20:09,249 UTC
    JobId: 56e9dfcb-6b64-4f9d-b137-171f538029d3
  3. Verify that the deleted account is no longer displayed in the user list.

    PCA-ADMIN> list User
    Command: list User
    Status: Success
    Time: 2021-08-25 09:22:07,743 UTC
    Data:
      id                                     name
      --                                     ----
      401fce73-5bee-48b1-b86d-fba1d85e049b   admin

Federating with Microsoft Active Directory

Many companies use an identity provider to manage user logins and passwords and to authenticate users for access to secure websites, services, and resources. To access the Oracle Private Cloud Appliance Service Web UI, users must also sign in with a user name and password. An administrator can federate with a supported identity provider so that each user can use their existing login and password, rather than having to create new credentials to access and use cloud resources.

Federation involves setting up a trust relationship between the identity provider and Private Cloud Appliance. When an administrator has established this relationship, federated users are prompted with a single sign-on when accessing the Service Web UI.

For more information, see "Federating with Identity Providers" in the chapter Identity and Access Management Overview of the Oracle Private Cloud Appliance Concepts Guide.

You can federate multiple Active Directory (AD) accounts with Private Cloud Appliance (for example, one for each division of the organization), but each federation trust that you set up must be for a single AD account. To set up a trust, you perform some tasks in the Private Cloud Appliance Service Web UI and some tasks in Active Directory Federation Services (ADFS).

Before you begin federating, make sure you already have:

  • Installed and configured Microsoft Active Directory Federation Services for your organization.

  • Set up groups in Active Directory that will map to groups in Private Cloud Appliance.

  • Created users in Active Directory who will sign into the Private Cloud Appliance Service Web UI.

Note:

Consider naming Active Directory groups that you intend to map to Private Cloud Appliance groups with a common prefix to make it easy to apply a filter rule, for example, PCA_Administrators, PCA_NetworkAdmins, PCA_InstanceLaunchers.

Gathering Required Information from ADFS

To federate with Oracle Private Cloud Appliance you need to have the SAML metadata document and the names of the Active Directory (AD) groups that you want to map to Private Cloud Appliance groups.

  1. Locate and download the SAML metadata document for your ADFS, which is by default at:

    https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml

    This is the document you will upload when you create the identity provider.

  2. Make a note of all the AD groups that you want to map to Private Cloud Appliance groups.

    Caution:

    Ensure that you have all the Private Cloud Appliance groups configured before you add AD as an identity provider.

Verifying Identity Provider Self-Signed Certificates

Caution:

You can skip this section if your ADFS certificate is signed by a known certificate authority because they should already exist in the Private Cloud Appliance certificate bundle.

The Oracle Private Cloud Appliance Certificate Authority (CA), is self-signed OpenSSL generated root and intermediate x.509 certificate. These CA certificates are used to issue x.509 server/client certificates allowing you to add outside Certificate Authority (CA) trust information to the rack. If you use a self-signed certificate for ADFS, you will need to add outside CA trust information from ADFS to the management nodes on the rack.

Note:

If you are using the metadataUrl property to create or update an identity provider, you will need to add the identity provider's web server's certificate chain to the Private Cloud Appliance outside CA bundle. See your identity provider's documentation on how to find the web server's certificate chain and then follow steps 3-8.

To add outside CA trust information, complete the following steps:

  1. From a browser, enter the following URL and download the SAML metadata document for your ADFS, which is by default at:

    https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
  2. Open the file in a text or XML editor and locate the signing certificate section, for example:

    <KeyDescriptor use="signing">
    <KeyInfo>
    <X509Data>
    <X509Certificate>
    <!--CERTIFICATE IS HERE-->
    </X509Certificate>
    </X509Data>
    </KeyInfo>
    </KeyDescriptor>
  3. Log on to management node 1 whose default name is pcamn01.

  4. Navigate to /etc/pca3.0/vault and create a new directory named customer_ca.

    Note:

    You can use this directory for multiple files. For example you can create a file for the identity provider certificate and one for the web server's certificate chain.

  5. In the customer_ca directory, create a new file in PEM format.

  6. Copy the certificate from the FederationMetadata.xml file, which is located within the <X509Certificate> tag, and paste into the new PEM file. Be sure to include the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, for example:

    -----BEGIN CERTIFICATE-----
    <CERTIFICATE CONTENT>
    -----END CERTIFICATE-----
  7. Save the file and close.

  8. Run the following command to update the ca_outside_bundle.crt on all management nodes:

    python3 /usr/lib/python3.6/site-packages/pca_foundation/secret_service/cert_generator/cert_generator_app.py -copy_to_mns

Managing Identity Providers

To federate with an identity provider in Oracle Private Cloud Appliance you create it in either the Service Web UI or the Service CLI and map account groups.

After you create your identity provider, you might have the need to make an update. For example, you will need to update your metadata XML file when it expires. You can also view all identity providers, view details of or delete an identity provider.

Adding Active Directory as an Identity Provider

To federate with Active Directory (AD) in Oracle Private Cloud Appliance you must add it as an identity provider. At the same time, you can set up the group mappings or you can set them up later.

To add AD as an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Sign in with your Private Cloud Appliance login and password.

  2. Open the navigation menu and click Identity Provider.

  3. On the Identity Providers page, click Create Identity Provider.

  4. On the Create an Identity Provider page, provide the following information:

    1. Display Name

      The name that the federated users see when choosing which identity provider to use for signing in to the Service Web UI. This name must be unique across all identity providers and cannot be changed.

    2. Description

      A friendly description of the identity provider.

    3. Authentication Contexts

      Click Add Class Reference and select an authentication context from the list.

      When one or more values are specified, Private Cloud Appliance (the relying party), expects the identity provider to use one of the specified authentication mechanisms when authenticating the user. The returned SAML response from the identity provider must contain an authentication statement with that authentication context class reference. If the SAML response authentication context does not match what is specified here, the Private Cloud Appliance authentication service rejects the SAML response with a 400.

    4. Encrypt Assertion (Optional)

      When enabled, the authorization service expects encrypted assertions from the identity provider. Only the authorization service can decrypt the assertion. When not enabled, the authorization service expects SAML tokens to be unencrypted, but protected, by SSL.

    5. Force Authentication (Optional)

      When enabled, users are always asked to authenticate at their identity provider when redirected by the authorization service. When not enabled, users are not asked to re-authenticate if they already have an active login session with the identity provider.

    6. Metadata URL

      Enter the URL for the FederationMetadata.xml document from the identity provider.

      By default, the metadat file for ADFS is located at

      https://<yourservername>/FederationMetadata/2007-06/FederationMetadata.xml
  5. Click Create Identity Provider.

    Your new identity provider is assigned an OCID and is displayed on the Identity Providers page

After the identity provider is added, you must set up the group mappings between Private Cloud Appliance and Active Directory.

To set up group mappings, see Creating Group Mappings.

Updating an Identity Provider

To update an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Open the navigation menu and click Identity Providers.

    A list of the identity providers is displayed.

  2. For the identity provider you want to update, click the Actions icon (three dots) and then click Edit.

  3. Change any of the following information; however, be aware that changing this information can affect the federation:

    1. Description

    2. Authentication Contexts

      Add or delete a class reference.

    3. Encrypt Assertion

      Enable or disable encrypted assertions from the identity provider.

    4. Force Authentication

      Enable or disable redirect authentication from the identity provider.

    5. Metadata URL

      Enter the URL for a new FederationMetadata.xml document from the identity provider.

    For more information, see step 4 in Adding Active Directory as an Identity Provider.

  4. Click Update Identity Provider.

Viewing Identity Provider Details

The identity provider details page displays general information such as authentication contexts. It also provides the identity provider's settings, which include the redirect URL.

From this page, you can also edit the identity provider and manage the group mappings.

To view details for an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Open the navigation menu and click Identity Providers.

    A list of the identity providers is displayed.

  2. For the identity provider whose details you want to view, click the Actions icon (three dots) and then click View Details.

    The identity provider details page is displayed.

Listing Identity Providers

To list the identity providers, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Open the navigation menu and click Identity Providers.

    A list of the identity providers is displayed.

Deleting an Identity Provider

If you want to remove the option for federated users to log into Private Cloud Appliance you must delete the identity provider, which also deletes all of the associated group mappings.

To delete an identity provider, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Open the navigation menu, click Identity and then click Federation.

    A list of the identity providers is displayed.

  2. For the identity provider you want to delete, click the Actions icon (three dots) and then click Delete.

  3. At the Delete Identity Provider prompt, click Confirm.

Working with Group Mappings for an Identity Provider

When working with group mappings, keep in mind the following:

  • A given Active Directory group is mapped to a single Oracle Private Cloud Appliance group.

  • Private Cloud Appliance group names cannot contain spaces and cannot be changed later. Allowed characters are letters, numerals, hyphens, periods, underscores, and plus signs (+).

  • You can't update a group mapping, but you can delete the mapping and add a new one.

Creating Group Mappings

After you have created an identity provider, you must create mappings from ADFS groups to Private Cloud Appliance groups.

To create a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each identity provider group you want to map.

Using the Service Web UI

  1. Open the navigation menu and click IDP Group Mappings.

    A list of the identity provider group mappings is displayed.

  2. Click Create Group Mapping.

    The IDP Group Mapping Form is displayed

  3. In the Name field, enter a name for the IDP group mapping.

  4. In the IDP Group Name field, enter the exact name of the identity provider group.

  5. From the Admin Group Name list, select the Private Cloud Appliance group you want to map to the identity provider group.

  6. Optionally, enter a Description of the group.

  7. Click Create IDP Group Mapping.

    The new group mapping is displayed in the list.

Updating a Group Mapping

To update a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each group mapping you want to map.

Using the Service Web UI

  1. Open the navigation menu and click IDP Group Mappings.

    A list of the identity provider group mappings is displayed.

  2. For the group mapping you want to update, click the Actions icon (three dots) and then click Edit.

    The IDP Group Mapping Form is displayed.

  3. Modify any of the following fields; however, be aware that changing this information can affect the federation:

    1. Name

    2. IDP Group Name

    3. Admin Group Name

    4. Description

  4. Click Modify IDP Group Mapping.

    The updated group mapping is displayed in the list.

Viewing Group Mappings

To view group mapping details, follow the procedure for either the Service Web UI or the Service CLI.

Using the Service Web UI

  1. Open the navigation menu and click IDP Group Mappings.

    A list of the identity provider group mappings is displayed.

Deleting a Group Mapping

To delete a group mapping, follow the procedure for either the Service Web UI or the Service CLI. Repeat the steps for each identity provider group you want to delete.

Using the Service Web UI

  1. Open the navigation menu and click IDP Group Mappings.

    A list of the identity provider group mappings is displayed.

  2. For the group mapping you want to delete, click the Actions icon (three dots) and then click Delete.

  3. At the Deleting IDP Group Mapping prompt, click Confirm.

Adding Private Cloud Appliance as a Trusted Relying Party in ADFS

Caution:

The Oracle Private Cloud Appliance certificate bundle must be added to Active Directory, so that ADFS can trust the Private Cloud Appliance certificate. If you do not do this, user logins will fail. For more information about the Private Cloud Appliance certificate bundle, see "Obtaining the Certificate Authority Bundle" in the chapter Working in the Compute Enclave of the Oracle Private Cloud Appliance User Guide.

To complete the federation process, you must add Private Cloud Appliance as a trusted relying party in ADFS and then add associated relying party claim rules.

Add Relying Party in ADFS

  1. In the Service Web UI on the Identity Providers page, view the following text block:

    You need the Private Cloud Appliance Federation Metadata document when setting up a trust with Microsoft Active Directory Federation Services or with other SAML 2.0-compliant identity providers. This is an XML document that describes the Private Cloud Appliance endpoint and certificate information. Click Here

  2. Click "Click Here".

    A metadata XML file opens in the browser with a URL similar to:

    https://adminconsole.system-name.domain-name/wsapi/rest/saml/metadata/
  3. Copy the metadata XML file URL.

  4. From the system installed with ADFS, open a browser window and paste the URL.

  5. Save the file making sure to use the .xml extension, for example, my-sp-metadata.xml.

  6. Go to the AD FS Management Console and sign in to the account you want to federate.

  7. Add Private Cloud Appliance as a trusted relying party.

    1. Under AD FS, right-click Relying Party Trusts and the select Add Relying Party Trust.

    2. In the Add Relying Party Trust Wizard Welcome page, select Claims Aware and then click Start.

    3. On the Select Data Source page, select "Import data about the relying party from a file".

    4. Click Browse and navigate to your my-sp-metadata.xml and then click Open.

    5. On the Specify Display Name page, enter a display name, add any optional notes for the relying party, and then click Next.

    6. On the Choose Access Control Policy page, select the type of access you want to grant and then click Next.

    7. On the Ready to Add Trust page, review the settings, and then click Next to save your relying party trust information.

    8. On the Finish page, check "Configure claims issuance policy for this application" and then click Close.

      The Edit Claim Issuance Policy dialog appears, which you can leave open for the next section.

Adding Relying Party Claim Rules

After you add Private Cloud Appliance as a trusted relying party, you must add the claim rules so that the elements required (Name ID and groups) are added to the SAML authentication response.

To add a Name ID rule:

  1. In the Edit Claim Issuance Policy dialog, click Add Rule.

    The Select Rule Template dialog is displayed.

  2. For Claim rule template, select Transform an Incoming Claim and then click Next.

  3. Enter the following:

    • Claim rule name: Enter a name for this rule, for example, nameid.

    • Incoming claim type: Select Microsoft Windows account name.

    • Outgoing claim type: Select a claim type, for example, Name ID.

    • Outgoing name ID format: Select Persistent Identifier.

    • Select Pass through all claim values and then click Finish.

      The rule is displayed in the rules list.

The Issuance Transform Rules dialog displays the new rule.

If your Active Directory users are in no more than 100 groups, you simply add the groups rule. However, if your Active Directory users are in more than 100 groups, those users cannot be authenticated to use the Private Cloud Appliance Service Web UI. For these groups, you must apply a filter to the groups rule.

To add the groups rule:

  1. In the Issuance Transform Rules dialog, click Add Rule.

    The Select Rule Template dialog is displayed.

  2. For Claim rule template, select Send Claims Using a Custom Rule and then click Next.

  3. In the Add Transform Claim Rule Wizard, enter the following:

    1. Claim rule name: Enter groups.

    2. Custom rule: Enter the custom rule.

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => issue(store = "Active Directory", types = ("https://auth.oraclecloud.com/saml/claims/groupName"), query = ";tokenGroups;{0}", param = c.Value);
    3. Click Finish.

The Issuance Transform Rules dialog displays the new rule.

Providing Federated Users Sign In Information

Before federated users can log in to the Private Cloud Appliance Service Web UI, you must provide them with the URL. You must also ensure that you have configured the groups mappings otherwise a federated user cannot do any work in Private Cloud Appliance.