4 Role Model

4.1 General

OPC UA defines a standard approach for implementing role-based security. Servers may choose to implement part or all of the mechanisms defined here. The OPC UA approach assigns Permissions to Roles for each Node in the AddressSpace. Clients are then granted Roles when they create a Session based on the information provided by the Client.

Roles are used to separate authentication (determining who a Client is with a user token and Client application identity) from authorization (Permissions determining what the Client is allowed to do). By separating these tasks Servers can allow centralized services to manage user identities and credentials while the Server only manages the Permissions for Roles on its Nodes.

OPC 10000-3 defines the possible Permissions and the representation as Node Attributes.

Figure 1 depicts the ObjectTypes, Objects and their components used to represent the Role management.

4.2 RoleSetType

4.2.1 RoleSetType definition

The RoleSet Object defined in OPC 10000-5 is a RoleSetType which is formally defined in Table 1.

The AddRole Method allows configuration Clients to add a new Role to the Server.

The RemoveRole Method allows configuration Clients to remove a Role from the Server.

4.2.2 AddRole Method

This Method is used to add a Role to the RoleSet Object defined in 4.3.

The combination of the NamespaceUri and RoleName parameters are used to construct the BrowseName for the new Node. The BrowseName shall be unique within the RoleSet Object.

If the optional Properties EndpointsExclude and ApplicationsExclude are available on the Role Object created with this Method, the initial values of the EndpointsExclude and ApplicationsExclude Properties shall be TRUE.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

OPC 10000-3 defines well-known Roles. If this Method is to be used to add a well-known Role, the name of the Role from OPC 10000-3 shall be used together with the OPC UA namespace URI. The Server shall use the NodeIds for the well-known Roles in this case. The NodeIds for the well-known Roles are defined in OPC 10000-6.

Signature

	AddRole (
		[in]	String 		RoleName,
	[in]	String 		NamespaceUri,
	[out]	NodeId 		RoleNodeId
		);
	

Method Result Codes

The AddRole Method representation in the AddressSpace is formally defined in Table 2.

4.2.3 RemoveRole Method

This Method is used to remove a Role from the RoleSet Object.

The RoleNodeId is the NodeId of the Role Object to remove.

The Server may prohibit the removal of some Roles because they are necessary for the Server to function.

If a Role is removed all Permissions associated with the Role shall be deleted. Ideally these changes should take effect immediately; however, some lag may occur.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	RemoveRole (
		[in]	NodeId RoleNodeId
		);
	

Method Result Codes

The RemoveRole Method representation in the AddressSpace is formally defined in Table 3.

4.3 RoleSet

The RoleSet Object defined in Table 4 is used to publish all Roles supported by the Server.

Servers should support the well-known Roles which are defined in OPC 10000-3.

The default Identities for the Anonymous Role shall be Identities with the criteriaType IdentityCriteriaType.Anonymous and the criteriaType IdentityCriteriaType.AuthenticatedUser. The Anonymous Role is the default Role which is always assigned to all Sessions. The Anonymous Role is the default Role which is always assigned to all Sessions.

The default Identities for the AuthenticatedUser Role shall be an identity with the criteriaType IdentityCriteriaType.AuthenticatedUser.

The default Identities for the TrustedApplication Role shall be an identity with the criteriaType IdentityCriteriaType.TrustedApplication.

A Server shall not allow changes to the Roles Anonymous, AuthenticatedUser and TrustedApplication.

A Server shall not allow the deletion of the well-known Roles Anonymous and AuthenticatedUser TrustedApplication.

The additional definition for the conformance units of the instances is defined in Table 5.

4.4 RoleType

4.4.1 RoleType definition

Each Role Object has the Properties and Methods defined by the RoleType which is formally defined in Table 6.

The Properties and Methods of the RoleType contain sensitive security related information and shall only be browseable, readable, writeable and callable by authorized administrators through an encrypted channel.

The configuration of the Roles is done through Method calls. The only exceptions are the ApplicationsExclude and EndpointsExclude Properties. The two Properties are configured with the Write Service. All other Properties are configured with the corresponding Method calls. The CurrentWrite bit of the AccessLevel Attribute for the Properties Identities, Applications and Endpoints shall be FALSE.

If the configuration of a Role is changed, the Role assignment to active Session shall be re-evaluated and applied.

The Identities Property specifies the currently configured rules for mapping a UserIdentityToken to the Role. If no user identity is configured for the Role, the Identities Property value is an empty array. If this Property is an empty array and CustomConfiguration is not TRUE, then the Role cannot be granted to any Session.

The Role shall only be granted to the Session if all of the following conditions are true:

The UserIdentityToken complies with Identities.

The Applications Property is not configured or the Client Certificate complies with the Applications settings.

The Endpoints Property is not configured or the Endpoint used complies with the Endpoints settings.

The ApplicationsExclude Property defines the Applications Property as an include list or exclude list.

If the ApplicationsExclude Property is not provided or has a value of FALSE then only ApplicationInstance Certificates included in the Applications Property shall be included in this Role. All other ApplicationInstance Certificates shall not be included in this Role.

If the ApplicationsExclude Property has a value of TRUE then all ApplicationInstance Certificates included in the Applications Property shall be excluded from this Role. All other ApplicationInstance Certificates shall be included in this Role.

The default value of the ApplicationsExclude Property shall be TRUE if the Applications Property has an empty array.

The Applications Property specifies the ApplicationInstance Certificates of Clients which shall be included or excluded from this Role. Each element in the array is an ApplicationUri from a Client Certificate which is trusted by the Server. If Applications has entries in the array, the Role shall only be granted if the Session uses a signed or signed and encrypted communication channel.

The EndpointsExclude Property defines the Endpoints Property as an include list or exclude list.

If the EndpointsExclude Property is not provided or has a value of FALSE then only Endpoints included in the Endpoints Property shall be included in this Role. All other Endpoints shall not be included in this Role.

If the EndpointsExclude Property has a value of TRUE then all Endpoints included in the Endpoints Property shall be excluded from this Role. All other Endpoints shall be included in this Role.

The default value of the EndpointsExclude Property shall be TRUE if the Endpoints Property has an empty array.

The Endpoints Property specifies the Endpoints which shall be included or excluded from this Role. Each element in the array is an EndpointType that contains an Endpoint description. The EndpointUrl and the other Endpoint settings are compared with the configured Endpoint that is used by the SecureChannel for the Session. The EndpointType DataType is defined in 4.4.2. Fields that have default values as defined in the EndpointType DataType are ignored during the comparison.

The CustomConfiguration Property indicates that the configuration of the Role and the assignment of the Role to Sessions is vendor specific. Roles are required to support the RolePermissions Attribute. If a Server want to support RolePermissions but is not able to support the standard Role functionality, it can indicate this with the CustomConfiguration Property. If CustomConfiguration is TRUE, the Server may hide the configuration options completely or the Server may provide additional vendor specific configuration options.

The AddIdentity Method adds a rule used to map a UserIdentityToken to the Role. If the Server does not allow changes to the mapping rules, then the Method shall not be present. A Server should prevent certain rules from being added to particular Roles. For example, a Server should refuse to allow an ANONYMOUS_5 (see 4.4.2) mapping rule to be added to Roles with administrator privileges.

The RemoveIdentity Method removes a mapping rule used to map a UserIdentityToken to the Role. If the Server does not allow changes to the mapping rules, then the Method shall not be present.

The AddApplication Method adds an ApplicationInstance Certificate to the list of Applications. If the Server does not enforce application restrictions or does not allow changes to the mapping rules for the Role the Method shall not be present.

The RemoveApplication Method removes an ApplicationInstance Certificate from the list of Applications. If the Server does not enforce application restrictions or does not allow changes to the mapping rules for the Role the Method shall not be present.

4.4.2 EndpointType

This structure describes an Endpoint. The EndpointType is formally defined in Table 7.

The EndpointType Structure representation in the AddressSpace is defined in Table 8.

4.4.3 IdentityMappingRuleType

The IdentityMappingRuleType structure defines a single rule for selecting a UserIdentityToken. The structure is described in Table 9.

If the criteriaType is UserName, the criteria is a name of a user known to the Server. For example, the user could be the name of a local operating system account or a user managed by the server as defined in 5.2.

If the criteriaType is Thumbprint, the criteria is a thumbprint of a user Certificate. For this criteria, the thumbprint shall be encoded as a hexadecimal string with upper case characters and without spaces.

If the criteriaType is Role, the criteria is a name of a restriction found in the Access Token. For example, the Role "subscriber" may only be allowed to access PubSub related Nodes. If the issuedTokenType of the Access Token is “http://opcfoundation.org/UA/UserToken#JWT”, the criteria contains one of the entries in the roles array of the JWT IssuedIdentityToken. If “iss” is present in the JWT IssuedIdentityToken, the criteria is prepended by the value of “iss” followed by a ‘/’ (slash).

If the criteriaType is GroupId, the criteria is a generic text identifier for a user group specific to the Authorization Service. For example, an Authorization Service providing access to an Active Directory may add one or more Windows Security Groups to the Access Token. OPC 10000-6 provides details on how groups are added to Access Tokens. If the issuedTokenType of the Access Token is “http://opcfoundation.org/UA/UserToken#JWT”, the criteria contain one of the entries in the groups array of the JWT IssuedIdentityToken. If “iss” is present in the JWT IssuedIdentityToken, the criteria is prepended by the value of “iss” followed by a ‘/’ (slash).

If the criteriaType is Anonymous, the criteria shall be null or an empty string. The criteriaType applies if no user credentials have been provided.

If the criteriaType is AuthenticatedUser, the criteria shall be null or an empty string. The criteriaType applies if any valid user credentials have been provided.

If the criteriaType is TrustedApplication, the criteria shall be null or an empty string. The criteriaType applies for any Client application with a trusted ApplicationInstance Certificate. The Client Certificate shall be trusted by the Server and the Session shall use at least a signed communication channel.

If the criteriaType is Application, the criteria is the ApplicationUri from the Client Certificate used for the Session. The Client Certificate shall be trusted by the Server and the Session shall use at least a signed communication channel. This criteria type is used if a Role should be granted to a Session for Application Authentication with Anonymous UserIdentityToken. If a Role should be granted to a Session for Application Authentication combined with User Authentication, the Applications Property on the RoleType is combined with the Identities Property on the RoleType as defined in 4.4.1.

If the criteriaType is X509Subject, the criteria is the X509 subject name of a Certificate of a user which is trusted by the Server or the X509 subject name of an issuer of the user Certificate. The format of the subject name criteria consists of a sequence of name value pairs separated by a '/'. The name shall be one of entries in Table 10 and shall be followed by a '=' and then followed by the value, which is always enclosed in double quotes ('"'). The order shall be by the order shown in Table 10 with the lowest number first. Every value from Table 10 present in the Certificate shall be included in the criteria, others must not be included. The value may be any printable character except for '"'. For example: CN="User Name"/O="Company". Table 10 contains all subject name attributes where support is required by X509 and some commonly used attributes where support is optional. Additional fields may be added in the future. If one name is used multiple times in the certificate, the name is also repeated in the criteria. The entries with the same name are entered in the order they appear in the Certificate. All names listed in Table 10 that are included in the X509 subject name shall match the content of the criteria String. Names not included in Table 10 are ignored.

The IdentityMappingRuleType Structure representation in the AddressSpace is defined in Table 11.

4.4.4 IdentityCriteriaType

The IdentityCriteriaType Enumeration is defined in Table 12.

Its representation in the AddressSpace is defined in Table 13.

4.4.5 AddIdentity Method

This Method is used to add an identity mapping rule to a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	AddIdentity (
		[in]	IdentityMappingRuleType Rule
		);
	

Method Result Codes

The AddIdentity Method representation in the AddressSpace is formally defined in Table 14.

4.4.6 RemoveIdentity Method

This Method is used to remove an identity mapping rule from a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	RemoveIdentity (
		[in]	IdentityMappingRuleType Rule
		);
	

Method Result Codes

The RemoveIdentity Method representation in the AddressSpace is formally defined in Table 15.

4.4.7 AddApplication Method

This Method is used to add an application mapping rule to a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	AddApplication (
		[in]	String ApplicationUri
		);
	

Method Result Codes

The AddApplication Method representation in the AddressSpace is formally defined in Table 16.

4.4.8 RemoveApplication Method

This Method is used to remove an application mapping rule from a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	RemoveApplication (
		[in]	String ApplicationUri
		);
	

Method Result Codes

The RemoveApplication Method representation in the AddressSpace is formally defined in Table 17.

4.4.9 AddEndpoint Method

This Method is used to add an endpoint mapping rule to a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	AddEndpoint (
		[in]	EndpointType Endpoint
		);
	

Method Result Codes

The AddEndpoint Method representation in the AddressSpace is formally defined in Table 18.

4.4.10 RemoveEndpoint Method

This Method is used to remove an endpoint mapping rule from a Role.

The Client shall use an encrypted channel and shall provide user credentials with administrator rights like SecurityAdmin Role when invoking this Method on the Server.

Signature

	RemoveEndpoint (
		[in]	EndpointType Endpoint
		);
	

Method Result Codes

The RemoveEndpoint Method representation in the AddressSpace is formally defined in Table 19.

4.5 RoleMappingRuleChangedAuditEventType

This Event is raised when a mapping rule for a Role is changed.

This is the result of calling any of the add or remove Methods defined on the RoleType.

It shall be raised when the AddIdentity, RemoveIdentity, AddApplication, RemoveApplication, AddEndpoint or RemoveEndpoint Method causes an update to a Role.

Its representation in the AddressSpace is formally defined in Table 20.

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantics are defined in OPC 10000-5.