Errata exists for this version of the document.

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.

The RoleSet Object defined in Table 10 is a RoleSetType which is formally defined in Table F.1.

Table F.1– RoleSetType Definition

Attribute	Value
BrowseName	RoleSetType
IsAbstract	False
References	Node Class	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of BaseObjectType defined in 6.2.
HasComponent	Object	<RoleName>		RoleType	OptionalPlaceholder
HasComponent	Method	AddRole	Defined in F.2.2		Mandatory
HasComponent	Method	RemoveRole	Defined in F.2.3.		Mandatory

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.

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

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.

This Method affects security and shall only be browseable and callable by authorized administrators.

OPC 10000-3 defines well-known Roles. If this Method is used to add a well-known Role, the name of the Role from OPC 10000-3 is 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

);

Argument	Description
RoleName	The name of the Role.
NamespaceUri	The NamespaceUri qualifies the RoleName. If this value is null or empty then the resulting BrowseName will be qualified by the Server’s NamespaceUri.
RoleNodeId	The NodeId assigned by the Server to the new Node.

Method Result Codes

ResultCode	Description
Bad_InvalidArgument	The RoleName or NamespaceUri is not valid. The text associated with the error shall indicate the exact problem.
Bad_NotSupported	The Server does not allow more Roles to be added.
Bad_UserAccessDenied	The caller does not have the necessary Permissions.

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 are deleted as well. Ideally these changes should take effect immediately, however, some lag may occur.

This Method affects security and shall only be browseable and callable by authorized administrators.

Signature

RemoveRole (

[in]NodeId RoleNodeId

);

Argument	Description
RoleNodeId	The NodeId of the Role Object.

Method Result Codes

ResultCode	Description
Bad_NodeIdUnknown	The specified Role Object does not exist.
Bad_NotSupported	The Server does not allow the Role Object to be removed.
Bad_UserAccessDenied	The caller does not have the necessary Permissions.
Bad_RequestNotAllowed	The specified Role Object cannot be removed.

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

Table F.2 – RoleType Definition

Attribute	Value
BrowseName	RoleType
IsAbstract	False
References	Node Class	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of BaseObjectType
HasProperty	Variable	Identities	IdentityMapping RuleType []	PropertyType	Mandatory
HasProperty	Variable	ApplicationsExclude	Boolean	PropertyType	Optional
HasProperty	Variable	Applications	String []	PropertyType	Optional
HasProperty	Variable	EndpointsExclude	Boolean	PropertyType	Optional
HasProperty	Variable	Endpoints	EndpointType []	PropertyType	Optional
HasComponent	Method	AddIdentity	Defined in F.3.3.		Optional
HasComponent	Method	RemoveIdentity	Defined in F.3.4.		Optional
HasComponent	Method	AddApplication	Defined in F.3.3.		Optional
HasComponent	Method	RemoveApplication	Defined in F.3.4.		Optional
HasComponent	Method	AddEndpoint	Defined in F.3.3.		Optional
HasComponent	Method	RemoveEndpoint	Defined in F.3.4.		Optional

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

The Identities Property specifies the currently configured rules for mapping a UserIdentityToken to the Role. If this Property is an empty array, then the Role cannot be granted to any Session.

The ApplicationsExclude Property defines the Applications Property as an include list or exclude list. If this Property is not provided or has a value of FALSE then only Application Instance Certificates included in the Applications Property shall be included in this Role. All other Application Instance Certificates shall not be included in this Role. If this Property has a value of TRUE then all Application Instance Certificates included in the Applications Property shall be excluded from this Role. All other Application Instance Certificates shall be included in this Role.

The Applications Property specifies the Application Instance 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.

The EndpontsExclude Property defines the Endpoints Property as an include list or exclude list. If this 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 include this Role. If this 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 Endpoints Property specifies the Endpoints which shall be included or excluded from this Role. The value is an EndpointType array which contains one or more Endpoint descriptions. The EndpointType DataType is defined in 12.22.

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 is not 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 F.3.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 is not present.

The AddApplication Method adds an Application Instance Certificate to the list of. If the Server does not enforce application restrictions or does not allow changes to the mapping rules for the Role the Method is not present.

The RemoveApplication Method removes an Application Instance 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 is not present.

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

Table F.3 – IdentityMappingRuleType

Name	Type	Description
IdentityMappingRuleType	Structure	Specifies a rule used to map a UserIdentityToken to a Role.
criteriaType	Enumeration Identity CriteriaType	The type of criteria contained in the rule. USERNAME_1The rule specifies a UserName from a UserNameIdentityToken; THUMBPRINT_2The rule specifies the Thumbprint of a User or CA Certificate; ROLE_3 The rule is a Role specified in an Access Token; GROUPID_4 The rule is a user group specified in the Access Token; ANONYMOUS_5The rule specifies Anonymous UserIdentityToken; AUTHENTICATED_USER_6The rules specify any non-Anonymous UserIdentityToken;
criteria	String	The criteria which the UserIdentityToken must meet for a Session to be mapped to the Role. The meaning of the criteria depends on the mappingType. The criteria are a “” for ANONYMOUS_5 and AUTHENTICATED_USER_6

If the criteriaType is USERNAME_1, 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.

If the criteriaType is THUMBPRINT_2, the criteria is a thumbprint of a Certificate of a user or CA which is trusted by the Server.

If the criteriaType is ROLE_3, 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 criteriaType is GROUPID_4, 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 criteriaType is ANONYMOUS_5, the criteria is a null string which indicates no user credentials have been provided.

If the criteriaType is AUTHENTICATED_USER_6, the criteria is a null string which indicates any valid user credentials have been provided.

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 when invoking this Method on the Server.

Signature

AddIdentity (

[in]IdentityMappingRuleType Rule

);

Argument	Description
Rule	The rule to add.

Method Result Codes

ResultCode	Description
Bad_InvalidArgument	The rule is not valid.
Bad_RequestNotAllowed	The rule cannot be added to the Role because of Server imposed restrictions.
Bad_NotSupported	The rule is not supported by the Server.
Bad_AlreadyExists	An equivalent rule already exists.

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

The Client shall provide user credentials with administrator rights when invoking this Method on the Server.

Signature

RemoveIdentity (

[in]IdentityMappingRuleType Rule

);

Argument	Description
Rule	The Rule to remove.

Method Result Codes

ResultCode	Description
Bad_NotFound	The rule does not exist.
Bad_UserAccessDenied	The session user is not allowed to configure the object.

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

The Client shall provide user credentials with administrator rights when invoking this Method on the Server.

Signature

AddApplication (

[in]String ApplicationUri

);

Argument	Description
ApplicationUri	The ApplicationUri for the application.

Method Result Codes

ResultCode	Description
Bad_InvalidArgument	The ApplicationUri is not valid.
Bad_RequestNotAllowed	The mapping cannot be added to the Role because of Server imposed restrictions.
Bad_AlreadyExists	The ApplicationUri is already assigned to the Role.
Bad_UserAccessDenied	The session user is not allowed to configure the object.

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

The Client shall provide user credentials with administrator rights when invoking this Method on the Server.

Signature

RemoveApplication (

[in]String ApplicationUri

);

Argument	Description
ApplicationUri	The ApplicationUri for the application.

Method Result Codes

ResultCode	Description
Bad_NotFound	The ApplicationUri is not assigned to the Role.
Bad_UserAccessDenied	The session user is not allowed to configure the object.

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

The Client shall provide user credentials with administrator rights when invoking this Method on the Server.

Signature

AddEndpoint (

[in]EndpointType Endpoint

);

Argument	Description
Endpoint	The Endpoint to add.

Method Result Codes

ResultCode	Description
Bad_InvalidArgument	The EndpointUrl is not valid.
Bad_RequestNotAllowed	The mapping cannot be added to the Role because of Server imposed restrictions.
Bad_AlreadyExists	The EndpointUrl is already assigned to the Role.
Bad_UserAccessDenied	The session user is not allowed to configure the object.

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

The Client shall provide user credentials with administrator rights when invoking this Method on the Server.

Signature

RemoveEndpoint (

[in]EndpointType Endpoint

);

Argument	Description
Endpoint	The Endpoint to remove.

Method Result Codes

ResultCode	Description
Bad_NotFound	The EndpointUrl is not assigned to the Role.
Bad_UserAccessDenied	The session user is not allowed to configure the object.

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 F.4.

Table F.4 – RoleMappingRuleChangedAuditEventType Definition

Attribute		Value
BrowseName		RoleMappingRuleChangedAuditEventType
IsAbstract		True
References	NodeClass		BrowseName	DataType	TypeDefinition	ModellingRule
Subtype of the AuditUpdateMethodEventType defined in 6.4.27

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantics are defined in 6.4.27.

______________