MCS Environments

28 MCS Environments

Your team's Oracle Mobile Cloud Service (MCS) subscription consists of at least one environment and offers distinct roles for team members.

As a mobile cloud administrator, you manage these environment service instances, their associated policies, and the permissions that team members have within them. To create and structure environments, see Create Mobile Environment Service Instances.

Team Members

In most cases, developing a mobile application is a team effort. Mobile application developers work closely with service developers and support personnel such as program managers and administrators. MCS makes the complexities of a large software development project easier to manage.

Depending on their assigned roles within an environment, team members can develop mobile backends, custom code, custom APIs, and use built-in services, such as Notifications, Storage, Analytics, and more. You can give team members wide access to features, environments, and user information, or restrict them to a small set of permissions. You must be an Oracle Cloud identity domain administrator to manage MCS team member roles. To control the access of your team members and manage the steps of your product development process using environments and roles, see Assign MCS Team Member Roles.

To see how team members access the MCS UI, see What is My Environment? As a mobile cloud administrator, you can manage artifacts and permissions in the environment from the Administration UI as described in Administration View.

Note:

Team members are users with access to MCS development features; these users are different from mobile users, the end users that access mobile applications running on MCS. To manage mobile users, see Set Up Mobile Users, Realms and Roles.

What is My Environment?

An environment is a predefined arena for working in MCS. Depending on your implementation of MCS and your role, you have access to one or more environments.

If you have access to multiple environments, you can always tell which environment you’re in by looking at the environment field at the top of the page:

Description of select_env-png.png follows

Description of the illustration select_env-png.png

To access environments, see Your Work Environment.

Each environment has its own set of policies that govern the behavior of artifacts within that specific environment. To learn about environment policies, see Environment Policies. CSF keys and security certificates are also unique to each environment, see CSF Keys.

Your Work Environment

You work in one environment at a time. The first time you log in to MCS, you’re put in the default environment set by the mobile cloud administrator. If you don’t have permission to access the default environment but you do have access to another environment, that environment is displayed instead. If MCS can’t determine which environment to open, an environment selector dialog opens that lets you select the environment.

After you’re logged in to MCS, you can select the environment you want to work in from the environment drop-down list. The list only includes environments that you have permission to access. To switch environments, see Changing Environments.

When you open the MCS side menu (click ) and select an artifact from Applications (for example Mobile Backends or Collections), you go to the top-level page for that artifact type where you’ll see a list of those artifacts in the current environment. When you select an artifact in the list, details for that artifact are displayed. See Managing an Artifact’s Lifecycle.

When you log in to MCS again, you’re put in the environment that you were in when your previous session was closed.

Changing Environments

You can always see which environment you’re in by looking at the top of the MCS page. If you have access to multiple environments, you’ll see a drop-down list next to the environment name.

Description of the illustration select_env-png.png

If you need access to an environment that you don’t see in the list, contact your mobile cloud administrator. See Changing Environment Views for the Administrator.

To change environments, click the environment name in the drop-down list. Be sure to save any unfinished work before switching environments.

What Happens When You Change Environments?

This discussion presumes your instance of MCS has more than one environment. When you switch to another environment, you’ll be moved to the same page that you’re currently viewing. That is, if you were on the Collections page in Environment A (the source environment), you’ll be on the Collections page when you move to Environment B (the target environment).

You won’t be able to access an artifact in another environment if one of the following conditions exist:

The target environment you want to switch to has been deleted.
For example, you’ve got an old bookmark to the details page for collection123 in Environment B. When you go to the bookmark, you’re told Environment B can’t be located. You’re no longer in any environment. Don’t worry, you’ve got some options:
- You can select another environment. The Alternative environment field lists all the environments for which you have access permission.
  
  If collection123 exists in the environment that you select, you’ll be taken to the details page of collection123 in that environment.
- You can click Home in the side menu to go back to the default environment.
  
  In the default environment, you can click and select Applications > Storage from the side menu to view the list of collections. If you don't see Storage under Applications, you need to request access permission to collections in the default environment from your mobile cloud administrator.
You don’t have access permission for the target environment.

For example, you get a link to view the details for collection123 in Environment B but you’re told that you can’t access the environment. You can select an alternative environment from the list of environments that you can access. Otherwise, contact your mobile cloud administrator to get access permission for the target environment.
You don’t have permission to view the artifact in the target environment.

For example, in Environment A you might be viewing analytical details on new users. You switch to Environment B to see analytic details for new users in that environment, but you’re told that you don’t have permissions to view that information in Environment B. You need to request read permission from your mobile cloud administrator for the artifact in the target environment or go to another environment.

Administration View

If you’re a mobile cloud administrator, you can go to the Administration view by clicking and selecting Administration from the side menu. From the Administration view, you can examine the details of an environment, such as its policies, CSF keys and certificates, logs, and more. If you have a multi-environment instance of MCS, you can click on a environment tab to see its details. If you’re viewing the default environment, you’ll see Default in the upper right corner above the chart.

Description of generic_admin_view.png follows

Description of the illustration generic_admin_view.png

The green (healthy), amber (severe), and red (adverse) traffic-light indicators give you a bird's eye view of how quickly and successfully requests are processed within each environment over the last minute.

When you select an environment, the page plots a grouped bar chart comparing the number of requests against response times. It also displays the number of client (4xx) and server (5xx) errors and the number of pending requests for the selected environment. When the indicators signal that the health of an environment has declined from healthy to severe or even adverse, you can drill down from this page to quickly diagnose the cause by viewing detailed logging information and error messages. For details about diagnostics, see Diagnostics.

Each environment has its own set of policies and permissions. Policies govern the behavior of artifacts within a specific environment. You can view the environment policy settings for a particular environment by clicking Export in a selected environment. See Environment Policies.

Permissions let you control which team members have access to which environments and to specific functionality in those environments. You can assign access permissions when you create a role. See Assign MCS Team Member Roles.

CSF keys and security certificates are also unique to each environment. See CSF Keys and Certificates.

Changing Environment Views for the Administrator

If you have a multi-environment instance of MCS, you can easily and quickly view details specific to an environment from the Administration view.

Click and select Administration from the side menu.
Click an environment tab to see information about it such as analytics or policies.

You can quickly verify whether the environment you’re currently viewing is the default environment by looking at the upper right corner of the Administration page.

Description of admin_defaultview.png follows

Description of the illustration admin_defaultview.png

Setting the Default Environment

If you have a multi-environment instance of MCS, you can set a default environment for users when they access MCS for the first time:

Click and select Administration from the MCS side menu.
Select an environment.
Click Settings next to the Default indicator.
(Optional) Enter a name if you want to change the current environment name.

The name should be 30 characters or less. You can use uppercase and lowercase letters, the integers 1 through 9, and spaces.
Select Set as default for first-time user access.

Environment Policies

Environment policies are environment settings and artifact properties that are specific to a particular environment. They let you override given values per environment.

Some things to note about environment policies:

Policies can always be modified.
Policies can never be published.
Policies can’t be deployed across environments. The same policy can exist in multiple environments at the same time but each instance of that policy is unique to the environment containing it. For example, if your instance of MCS had Development, Staging, and Production environments, they can all have a Network_HttpRequestTimeout policy, but the policy in the Staging environment is applicable only to the APIs in the Staging environment.

Even though an artifact can’t be changed after it’s published, its behavior can still be affected after it’s deployed to another environment. If you’re a mobile cloud administrator, you have the flexibility to adjust policy values to better fit the required behavior of artifacts in a particular environment. For instance, if you’re in a development environment, you may be interested only in verifying that a connector’s endpoints are valid. The timeout values aren’t much of a concern during the experimental phase, but when you deploy that connector to the runtime environment, it’s available for wide use and realistic timeout settings are required. You’ll want to adjust the value of the Network_HttpRequestTimeout policy in the runtime environment accordingly.

Only mobile cloud administrators can deploy an artifact and, therefore are the only ones who can modify environment policies. You can modify policies when you deploy an artifact (mobile backend, custom API, API implementation, connector, collection, or realm) or by editing the policies.properties file for an environment directly from the Administration view. To change policy settings, see Modifying an Environment Policy. For descriptions of environment policies and their values, see Oracle Mobile Cloud Service Environment Policies.

In general, you should use the policy’s default settings. Changing the setting of a policy that has an environment scope can have adverse results. When you set a policy at the environment level, the value for that policy is applied to the relevant artifacts in that environment. For example, if you set the value of the Sync_CollectionTimeToLive policy to a value other than the default in the runtime environment, that value is applied to all mobile backends in that environment.

For information on a policy’s scope, see Environment Policy Scopes.

Environment Policy Names

A policy is simply a name-value pair. A policy name has the format mbeArtifactIdentity.invocableArtifactIdentity.policyPropertyName, and each part of the name has the following function:

The first mbeArtifactIdentity binds the policy value to a specific mobile backend.
The second invocableArtifactIdentity binds the policy to an API, an API implementation, or connector.
The policyPropertyName is the short name of the policy, which usually indicates the function of the policy, for example, Logging_Level or User_DefaultUserRole (note that property names are initial-capped and preceded by a category).

You can set mbeArtifactIdentity and invocableArtifactIdentity in one of the following ways:

The artifact name and version, which matches the artifact of a particular type with the given name and its version, for example, myMobileBackend(1.0.0).
The artifact name alone, which matches all artifacts of the same type with the given name and any version, for example, myMobileBackend.
A wildcard denoted by an asterisk (*), which matches all artifacts of the particular type.

Qualifying API Types

When you define a policy that affects an API, you must use a fully qualified name (which consists of an API category and the API name). The API category can be one of custom, connector, platform, or system. For example:

*.custom/myAPI(1.0)
*.connector/myAPI(1.0)
*.platform/myAPI(1.0)
*.system/myAPI(1.0)

Policy names for API implementations do not include category types. For example, *.myAPIImpl(1.0).

Examples of Policy Names

Here are some examples of policy names and their meanings:

myMBE(1.0).custom/myAPI(1.0).someProperty is applied to calls of a custom API or API implementation named myAPI that has a version of 1.0 within the context of a mobile backend named myMBE with a version of 1.0.
myMBE(1.0).connector/myAPI(1.0).someProperty is applied to calls of a connector API or API implementation named myAPI that has a version of 1.0 within the context of a mobile backend named myMBE with a version of 1.0.
myMBE.custom/myAPI(1.0).someProperty is applied to calls of a custom API or API implementation named myAPI that has a version of 1.0 within the context of a mobile backend named myMBE of any version.
*.custom/myAPI(1.0).someProperty is applied to calls of a custom API or API implementation named myAPI that has a version of 1.0 within the context of any mobile backend.
*.myAPIImpl(1.0).someProperty is applied to calls of an API implementation named myAPIImpl that has a version of 1.0 within the context of any mobile backend.
*.*.someProperty is applied to calls of any API or API Implementation within the context of any mobile backend. This name format denotes an environment wide policy.

Policy Property Names

Property names should follow the format Category_PropertyName. Property names should consist only of alphabetic characters and multi–part names should use CamelCase capitals, for example, Network_HttpReadTimeout. Names should not include the scope or an object type or unit of measure.

Environment Policy Scopes

When setting a policy, you should be aware of its scope. A policy’s scope refers to the artifacts to which a policy setting applies. Each policy has a unique set of scopes for which it’s valid. While some policies can be set at the environment-level and at the artifact-level, it may make more sense to set them at one particular level. For instance, the Connector_Endpoint policy stores the endpoint URL of a specific connector. This policy must be set on an individual connector basis and should be set at the artifact-level. The Network_HttpRequestTimeout policy on the other hand affects APIs and connectors. It needs to be set at the environment-level so that it’s applied to all APIs and connectors.

How you name a policy can determine its scope. Use the mbeAssetIdentity and the invocableAssedIdentity parts of the name to set whether a policy has an environment or artifact-level scope:

Environment scope: Set both mbeAssetIdentity and the invocableAssedIdentity as wildcards so that the policy is applied globally across the environment.

Example: *.*.Logging_Level=800
Mobile Backend scope: Set mbeAssetIdentity to a specific mobile backend and set the invocableAssedIdentity as a wildcard so that the policy is applied to all APIs and connectors called in the context of the given mobile backend. You make this more specific by including the version of the mobile backend.

Example: MyMobilBackend(1.3).*.Logging_Level=800
API scope: Set mbeAssetIdentity to a wildcard and set the invocableAssedIdentity to a specific API so that the policy is applied to that particular API when called in the context of the any mobile backend in that environment. You make this more specific by including the version of the API.

Example: *.custom/MyApi(2.0).Logging_Level=800
API Implementation scope: Set mbeAssetIdentity to a wildcard and set the invocableAssedIdentity to a specific API implementation so that the policy is applied to that particular implementation when called in the context of the any mobile backend in that environment. You make this more specific by including the version of the API.

Example: *.MyApiImpl(1.0).Logging_Level=800
Connector scope: Set mbeAssetIdentity to a wildcard and set the invocableAssedIdentity to a specific connector so that the policy is applied to that particular connector when called in the context of the any mobile backend in that environment. You make this more specific by including the version of the API.

Example: *.connector/MyConnector(2.2).Logging_Level=800
Fully-qualified API scope: Set the mbeAssetIdentity to a specific mobile backend and set the invocableAssedIdentity to a specific API so that the policy is scoped at the fully qualified API level whenever the API is called within the scope of the given mobile backend. You make this more specific by including the versions of the mobile back and the API.

Example: MyMBE(1.3).custom/MyApi(2.0).Logging_Level=800
Fully-qualified API Implementation scope: Set the mbeAssetIdentity to a specific mobile backend and set the invocableAssedIdentity to a specific API Implementation so that the policy is scoped at the fully qualified API implementation level whenever the implementation is called within the scope of the given mobile backend. You make this more specific by including the versions of the mobile back and the API implementation.

Example: MyMobileBackend(1.3).MyApiImpl(1.0).Logging_Level=800
Fully-qualified Connector scope: Set the mbeAssetIdentity to a specific mobile backend and set the invocableAssedIdentity to a specific connector so that the policy is scoped at the fully qualified connector level whenever the connector is called within the scope of the given mobile backend. You make this more specific by including the versions of the mobile back and the connector.

Example: MyMobileBackend(1.3).connector/MyConnector(2.2).Logging_Level=800

For details about policy name formats, see Environment Policy Names.

Modifying an Environment Policy

MCS generates a policies.properties file for you. If you’re a mobile cloud administrator, you can modify an environment policy by editing its value, saving your changes, and importing the modified file from the Administration view.

Click and select Administration from the side menu.
Click the environment for which you want to edit policy values.
Click Export under Policies.
Edit the policies as needed for the selected environment and save the file.
Import the modified policies.properties.

Here’s an example of a policies.properties file in a development environment:

Description of envpolicies_file.png follows

Description of the illustration envpolicies_file.png

Removing Environment Policies

Let’s say you created an artifact some time ago that became obsolete and has been purged. You want to reduce clutter in the policies.properties file by removing policies defined for the obsolete artifact. You can delete the policies, however, the process involves deleting all the policies within a given environment and replacing them with the policies from the modified policies.properties file that you import. Be very careful when deleting policies to ensure you don't remove the wrong ones.

To remove environment policies:

Click and select Administration from the side menu.
Be sure you're in the environment containing the policies you want to delete.
Click Export.
Make a copy of the exported policies.properties file.
Important: If, after you've imported the modified file, you find you've accidentally deleted policies that you need, you can restore the environment back to its previous state by deleting the all policies and importing the backup copy of the file.
Delete the policies you want to remove and save the file.
Select Delete all policies before import.
Import the modified policies.properties file.

All the previous environment policies are deleted and the environment contains only the policies imported from your modified file.

CSF Keys and Certificates

MCS uses the Credential Store Framework (CSF) to manage credentials in a secure form. CSF lets you store, retrieve, update, and delete credentials for a web service and other apps.

CSF keys are credentials that certify the authority of users and system components that are used during authentication and authorization. A CSF key uses basic authentication (user name and password) to generate a unique key value.

Certificates, which are electronic documents that are used authenticate an individual or organization, are stored in different keystores by type. Other certificates that you can create using the CSF Keys & Certificates dialog are:

Web Service Certificates, which can be trusted certificates (that is, a certificate containing only a public key) or a certificate that contains both public and private key information. Web Service Certificates are stored in the Oracle WSM Keystore.
Token (Signing) Certificates, which are standard X509 certificates that are used to securely sign all tokens issued by a federation server.
Secure Sockets Layer (SSL) Certificates, which are trusted certificates that you use to establish SSL communication with the external service. SSL Certificates are stored in the Trust Keystore.

You can also create a token issuer, which allows identity tokens provided by trusted third parties to be accepted and verified for authenticating mobile users. In the case of virtual users, identity tokens provided by third-party providers are used to both authenticate and authorize mobile users.

CSF keys, certificates, and their values are specific to the environment in which they are defined. It’s possible for keys with the same key name to exist with different values in multiple environments. Only the CSF keys and certificates in use in the selected environment are listed in the CSF Keys & Certificates dialog. A different set of keys and certificates can be displayed when this dialog is opened in another environment.

Token Certificates and Token Issuers

If you have identity tokens that are provided by third parties, you can add Token Issuer Certificate and Signing Authority Certificate information, along with any intermediate certificates, to establish a chain of trust. This lets MCS accept and verify identity tokens issued by third parties for authenticating mobile users.

Through the CSF Keys & Certificates dialog, you can do the following:

Create a token certificate.
Create a token issuer and associate certificates with that issuer.
Create a data bound rule, a setting that specifies how third-party tokens are processed per certificate.

Viewing Available CSF Keys, Certificates, and Token Issuers

As administrator, you manage the credential keys and certificates used by service developers when setting security policies. You can view the details of CSF keys and the definitions of certificates from the CSF Keys & Certificates dialog. You can also edit the details of a CSF key (except for the key name and alias) and review the list of available token issuers.

To view a key, certificate, or token issuer:

Click and select Administration from the side menu.
Click Keys & Certificates.
Click the CSF Keys, Certificates, or Token Issuer tab.
Select an alias in the Available Keys or Available Certificates list to view the details of the key or certificate.
1. For CSF Keys, select Show only referenced keys with null values to see only keys that are referenced by artifacts that have no credentials values.
  If you edit the description, user name, or password of a CSF key (the key name can’t be changed), click Save to save your changes and continue working in the dialog. Click Save and Close to save your actions and return to the main menu. Click Cancel to close the dialog without saving your changes.
2. For Web Service, Token, and SSL Certificates, click Export to save the selected certificate to a file. You can then import the certificate for use in another instance.

To add more CSF keys or certificates, see Configuring a CSF Key, Configuring a Web Service or Token Certificate, and Configuring an SSL Certificate.

Configuring a CSF Key

You can configure a new CSF key from the CSF Keys tab in the CSF Keys & Certificates dialog.

Click the CSF Keys tab.
Click Add and provide the following values:
- Unique key name. This name can’t be changed after the key is created.
- User name and password for the external system that requires this key for access.
Save the key.

Configuring a Web Service or Token Certificate

You can configure a new Web Service or Token Certificate from the Web Service and Token Certificates tab in the CSF Keys & Certificates dialog. You can’t edit a certificate after you’ve created it.

Click the Web Service and Token Certificates tab.
Click Add and provide the following information:
- Alias — Enter a unique name for the certificate.
- Content — Copy the certificate definition into the text field. You can get Web Service certificate content from the system administrator of the service, or token certificate content from the remote identity provider.
Save the certificate.

Note:

When a certificate is uploaded, it takes a few seconds before the certificate is available. Token certificates can take up to ten minutes.

To delete a certificate, click X by the selected alias in the list of Available Certificates. You can only delete certificates that you created.

Configuring an SSL Certificate

You can configure a new SSL Certificate from the SSL Certificates tab in the CSF Keys & Certificates dialog. You can’t edit a certificate after you’ve created it.

Click the SSL Certificates tab.
Click Add and provide the following information:
- Alias — Enter a unique name for the certificate.
- Content — Copy the certificate definition into the text field. You can get Web Service certificate content from the system administrator of the service, or token certificate content from the remote identity provider.
Save the certificate.

Note:

When a certificate is uploaded, it takes a few seconds before the certificate is available.

To delete a certificate, click X by the selected alias in the list of Available Certificates. You can only delete certificates that you created.

Disabling SSL Hostname Verification

Testing connectors can be difficult when they call an outbound service over SSL. If the SSL certificate has an incorrect or missing hostname, the developer might not be able to create the connector or might just have problems with testing.

You can make it easier to test a connector by turning off hostname verification for outbound SSL connections through the Security_IgnoreHostnameVerification policy.

Caution:

Turning off hostname verification is a security risk. Setting this policy to true should be limited to development. When testing is complete, set the policy back to its default value of false.

This policy is set globally (*.*.Security_IgnoreHostnameVerification) and will affect all connectors. Setting the scope for a specific backend or connector is not supported.

For more information on configuring policies, see Environment Policies.

Note:

Even if SSL hostname verification is disabled, you still need to import the SSL certificate if it's self-signed.

Adding a Token Issuer

To authenticate users with third-party tokens, you need to register the token issuers and associate them with their certificates.

After you’ve added at least one token certificate, use the steps below to add a token issuer from the Keys & Certificates dialog:

Click the Token Issuers tab.
Click New Issuer.
Enter the name of the token issuer in the Name field under Issuer Details.
Click Add (+) and select at least one name from the Select Certificate Subject Names dialog. All the certificates that have been uploaded are listed.
Save the token issuer.
If the list on the Token Issuers tab doesn’t include your new issuer, click Save in the tab to update the list.
(Optional) Click Rules to configure a rule for a certificate subject name.

Rules for Certificate Subject Names

You set rules to define filters, which determine whether or not a given token is considered valid. The type of rules you can select depends on whether virtual users are enabled or not.

If virtual users are disabled, you can set a User Mapping rule that specifies how the token subject content is used to identify the user record in SIM.

If virtual users are enabled, you can set a Default Roles rules that lists one or more default roles that are applied to all requests for all users. You can also define a Role Attribute rule that can contain one or more attribute names. If the token role names are different from MCS role names, you can additionally set role mapping rules to match the token roles names to the MCS role names.

Filter rules can be applied regardless of whether virtual users are enabled or not. Filter rules accept or reject a token based on whether its content matches the information in the token certificate. To get a full description of all the rules, see Rule Types. Filter rules can be applied regardless of whether virtual users are enabled or not. Filter rules accept or reject a token based on whether its content matches the filter rules associated with the token certificate.

Configuring Rules

Rules govern how tokens provided by token issuers are processed. If the token provided by a token issuer doesn’t meet the criteria specified by the rule, the request is rejected.

After you’ve added at least one token certificate and created a token issuer, you can configure a rule for the certificate subject name from the Token Issuer tab in the Keys & Certificates dialog.

On the Token Issuers tab, select a certificate subject name from the list.
Click Rules. As you add rules, the current number of rules is indicated on the Rules button.
Select Enable Virtual User if you’re configuring rules for users that aren’t registered.
With virtual users enabled, a token identifies a user with a record in Oracle Cloud, but roles are associated with the user based on the default content in the token, instead of on information in that account.
Under Add a New Rule, select the rule type.
Enter the required values for the rule type.
Click Add.

If you need to change a rule, just select it, make the updates and click Done. To delete a rule, select the rule and click X.

Rule Types

Filter Rule

The Filter rule consists of a token attribute and at least one value that must match the value associated with the token. The name-id attribute represents the username identified in the token, while the user.tenant.name attribute represents the tenant name associated with the token.

Use a comma-separated list to enter multiple attribute values for either attribute. If none of the values match, the token is deemed invalid. A value can contain a wildcard (*) character.

For example:

name-id=jack, jill, ann
user.tenant.name=testing, development

You can configure only one Filter rule per token attribute (that is, you configure one Filter rule with the name-id attribute and one Filter rule with the user.tenant.name attribute).

User Mapping Rule

The User Mapping rule defines how tokens are mapped to users, either by user name or email address. This rule is applicable only to JWT tokens, only if virtual users are disabled.

The rule consists of a token attribute, name-id, that represents the username identified in the token, and a user attribute name value of either uid or mail:

uid is the user’s username in the associated Cloud Account (default behavior)
mail is the user’s email address in the associated Cloud Account

You can configure only one User Mapping rule per issuer certificate name. If you don’t configure a User Mapping rule, name matching is used (the default behavior).

Note:

For SAML tokens the User Mapping rule type is ignored and the default behavior is to map the username in the token to the username in the associated record.

Default Role Rule

The Default Role rule defines a list of roles to associate with users. This rule is applicable only if virtual users are enabled.

The rule consists of a list of role names that are assigned to all users presenting tokens verified using the corresponding token certificate. Use a comma-separated list to enter multiple attribute values.

For example:role=technician, manager, tester

You can configure only one Default Role rule per issuer certificate name. If you don’t configure a Default Role rule, no roles are assigned to the requesting user unless you’ve configured a Role Attribute rule.

Role Attribute Rule

Use the Role Attribute rule to determine which roles to assign by examining the attributes in the token. If a Role Attribute role is defined, the token is searched for attributes with names that match any of the values defined in the rule. If matches are detected, the values of those token attributes are interpreted as roles and assigned to the virtual user. This rule is applicable only if virtual users are enabled.

The rule consists of a comma-separated list of token attribute names used to derive the roles that are assigned to users.

For example: employeelevel, QAgroup

You can configure only one Role Attribute rule per issuer certificate name, but you can use this rule in combination with the Role Mapping rule. If you don’t configure a Role Attribute rule, no roles are assigned to the requesting user unless you’ve configured a Default Role rule.

Note:

If you configure both the Default Role rule and the Role Attribute rule and the role attribute you defined is present in the token, the Default Role rule is ignored. However, if the defined role attribute isn’t present, the roles specified in the Default Roles rule are applied to the virtual user. Role Mapping rules can also define which roles to use when no matches are found.

Role Mapping Rule

The Role Mapping rule associates roles with role attributes in the token identified by the Role Attribute rule. This rule is applicable only if virtual users are enabled.

The rule consists of an external role name, which is the value that should be found in one or more token attributes, and a list of roles to which the external role names are mapped. Use a comma-separated list to enter multiple attribute values.

For example: employee=technician, manager, tester

This example maps the external role name, employee, to the existing roles, technician, manager, tester.

Note:

Role Mapping rules only work in conjunction with Role Attribute rules. If no Role Attribute rule is defined, Role Mapping rules are ignored. If the names of the token attributes configured in the Role Attributes rule don’t match the external role names configured in the Role Mapping rule, the token attributes are treated as role names and are assigned to the requesting user. If the role names defined in the rule don’t correspond to any existing roles, the value is ignored.

You can configure as many Role Mapping rules per issuer certificate as you need, but only one rule can be configured for each external role name. To map one external role to multiple roles, use a single rule and include all the roles in a comma-separated list, as shown in the example above.

Rule Examples

Here are some examples of setting different types of rules for certificate subject names.

User Mapping Rule with a JWT Token, and a SIM User

The setup: You have a SIM user and a JWT token. The JWT token contains an attribute called Subject with the value, mary.keane@fixitfast.com.

In the SIM, there’s a corresponding entry for the SIM user with the following attributes and values:

uid	mail	roles
`mkeane`	`mary.keane@fixitfast.com`	`manager`

You configure a User Mapping Rule with a token attribute value of name-id and user attribute value of mail.

What happens: The token is mapped to the SIM entry, mary.keane@fixitfast.com, and is assigned the role of manager.

User Mapping Rule, a SAML Token, and a SIM User

The setup: You have a SIM user and a SAML token. The SAML token contains an attribute called Subject with the value, mary.keane@fixitfast.com.

In the SIM, there’s a corresponding entry for the SIM user with the following attributes and values:

uid	mail	roles
`mkeane`	`mary.keane@fixitfast.com`	`manager`

You configure a User Mapping Rule with a token attribute value of name-id and user attribute value of mail.

What happens: Remember, for SAML tokens, the User Mapping Rule is ignored and the default behavior of name matching is used, that is, you can only map the name-id value in the token to the uid attribute in the SIM. The name-id is mapped to mkeane and is assigned the role of manager.

Default Roles Rule and a Virtual User

The setup: You have a virtual user and a SAML token. The token contains a Subject attribute with the value mary.keane.

You configure a Default Role rule with the values director and technician, which are roles that have been defined in MCS.

Rule	Values
`Default Role`	`director, technician`

What happens: The virtual user is assigned the roles of director and technician.

Role Attributes Rule and a Virtual User

The setup: You have a virtual user and a SAML token. The token contains a Subject attribute with the value, mary.keane and a Custom-Roles attribute with the values, director and technician.

You configure a Role Attributes rule with a token attribute called Custom-Roles.

What happens: A match is found between the token role attribute and the MCS role you configured. The virtual user is assigned the roles of director and technician.

Role Attributes Rule with a Role Mapping Rule and a Virtual User

The setup: You have a virtual user and a SAML token. The token contains a Subject attribute with the value, mary.keane and a token attribute called Custom-Roles with the values, director and technician.

Rule	Values
`Custom-Roles`	`director, technician`

You configure a Role Attribute rule with a token attribute name also calledCustom-Roles .

In addition, you configure a two Role Mapping rules, one with the external role name director with the values supervisor and manager, and another with the external role name of technician and the MCS role developer.

External Role Name	MCS Roles
`director`	`supervisor, manager`
`technician`	`developer`

What happens: The virtual user is assigned the roles of supervisor, manager, and developer.

What if you had configured only one Role Mapping rule, with the role name of director with the MCS roles of supervisor and manager?That is, you didn’t configure a Role Mapping rule for the external role, technician.

What happens: The virtual user is assigned the roles of supervisor and manager. The technician role is ignored.

Native Builds

The mobile apps built with MAX can run within the container of the MAX App, or, after Mobile OS Native Build Service packages them as APK or IPA files, they can run as native apps as well.

Oracle Developer Cloud Service (ODCS) packages the mobile app metadata as APK and IPA files. Unlike the apps that run within the MAX APP, these apps run natively on iOS phones and Android devices. Despite this difference, users download these apps in the same way that they download the apps that run within the container: by scanning the QR code that the MAX Designer generates when it completes a test or production build. Whether you distribute the app through the Apple Store or Google Play (or in this case, through QR codes), you always need to get the platform-specific trust certificates that enable the app to run on the device. You can find out more about what you need to do to prepare your apps for release and distribute them in the Apple and Google documentation.

Besides the credentials for app distribution, you also need the following:

The URL of your ODCS instance.
The name of the native build service project in ODCS.
The name and password that belong to the member of the build service project.

The general process setting up the user and the project are:

Logging into your Shared Identity Management (SIM) system as an administrator and then creating the user for the native build service. For example, create a user called MAXBuildsUser.

Note:
This is not an actual user (meaning that this account doesn’t belong to a human). This user is a safeguard that guarantees the availability of the native build service. If this were a real user, the build service would fail if the account is deactivated.
Adding the DEVELOPER_USER role to this user.
Logging into ODCS as an administrator and then creating a new project with a name like MAXBuilds.
Adding the build service user as a member of this project.

With this information and the platform-specific credentials in hand, you can now add native builds to each app that’s created using MAX. That means that in addition to the QR code for the MAX App, MAX presents another set of QR codes for the native builds.

How Do I Enable Native Builds?

You enable MAX users to build and distribute native apps by configuring the Native Build Service as follows:

In the Admin page, click Mobile OS Native Build Service.
Enter the ODCS information:
- Enter the base URL for your ODCS instance. For example, enter a URL like https://developer.us.oraclecloud.com/xx-xx.
- Enter the project name.
- Enter the project member name.
- Enter the password.
Click Test Connection.
Add the platform security certificates.
1. For Android:
  - Upload the keystore file.
  - Enter the Keystore password, Keystore Alias, and the Alias Password.
2. For iOS:
  - Add the P12 Certificate.
  - Enter the P12 Certificate password.
  - Add the Provisioning Profile.
  - Enter the Certificate Common Name (CN).
Click Save. From this point forward, the builds will include QR codes for the native platforms.