Each Role Objecthas the Propertiesand Methodsdefined by the RoleTypewhich is formally defined in Table 4.
Value |
|||||
BrowseName |
RoleType |
||||
IsAbstract |
False |
||||
References |
NodeClass |
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 |
HasProperty |
Variable |
CustomConfiguration |
Boolean |
PropertyType |
Optional |
HasComponent |
Method |
AddIdentity |
Defined in 4.4.5. |
Optional |
|
HasComponent |
Method |
RemoveIdentity |
Defined in 4.4.6. |
Optional |
|
HasComponent |
Method |
AddApplication |
Defined in 4.4.7. |
Optional |
|
HasComponent |
Method |
RemoveApplication |
Defined in 4.4.8. |
Optional |
|
HasComponent |
Method |
AddEndpoint |
Defined in 4.4.9. |
Optional |
|
HasComponent |
Method |
RemoveEndpoint |
Defined in 4.4.10. |
Optional |
|
Conformance Units |
|||||
Base Info ServerType |
The Propertiesand Methodsof the RoleTypecontain sensitive security related information and shall only be browseable, readable, writeable and callable by authorized administrators through an encrypted channel.
The configuration of the Rolesis done through Methodcalls. The only exceptions are the ApplicationsExcludeand EndpointsExclude Properties. The two Propertiesare configured with the Write Service. All other Propertiesare configured with the corresponding Methodcalls. The CurrentWritebit of the AccessLevel Attributefor the Properties Identities, Applicationsand Endpointsshall be FALSE.
The Identities Propertyspecifies the currently configured rules for mapping a UserIdentityTokento the Role. If this Property is an empty array and CustomConfigurationis not TRUE, then the Rolecannot be granted to any Session.
The Roleshall only be granted to the Sessionif all of the following conditions are true:
- The UserIdentityTokencomplies with Identities.
- The Applications Propertyis not configured or the Client Certificatecomplies with the Applicationssettings.
- The Endpoints Property is not configured or the Endpointused complies with the Endpointssettings.
The ApplicationsExclude Propertydefines the Applications Propertyas an include list or exclude list. If the ApplicationsExclude Propertyis not provided or has a value of FALSEthen only ApplicationInstance Certificatesincluded in the Applications Propertyshall be included in this Role. All other ApplicationInstance Certificatesshall not be included in this Role. If this Propertyhas a value of TRUEthen all ApplicationInstance Certificatesincluded in the Applications Propertyshall be excluded from this Role. All other ApplicationInstance Certificatesshall be included in this Role. If the Applications Propertyis provided with an empty array and all ApplicationInstance Certificatesshould be included, the ApplicationsExclude Propertyshall be present and the value must be TRUE.
The Applications Propertyspecifies the ApplicationInstance Certificatesof Clientswhich shall be included or excluded from this Role. Each element in the array is an ApplicationUrifrom a Client Certificatewhich is trusted by the Server. If Applicationsare configured for include or exclude, the Roleshall only be granted if the Sessionuses at least a signed communication channel.
The EndpointsExclude Propertydefines the Endpoints Propertyas an include list or exclude list. If this Propertyis not provided or has a value of FALSEthen only Endpointsincluded in the Endpoints Propertyshall be included in this Role. All other Endpointsshall not be included in this Role. If this Propertyhas a value of TRUEthen all Endpointsincluded in the Endpoints Propertyshall be excluded from this Role. All other Endpointsshall be included in this Role. If the Endpoints Propertyis provided with an empty array and all endpoints should be included, the EndpointsExclude Propertyshall be present and the value must be TRUE.
The Endpoints Propertyspecifies the Endpoints which shall be included or excluded from this Role. Each element in the array is an EndpointTypethat contains an Endpointdescription. The EndpointUrland the other Endpointsettings are compared with the configured Endpointthat is used by the SecureChannelfor the Session. The EndpointType DataTypeis defined in 4.4.2. Fields that have default values as defined in the EndpointType DataTypeare ignored during the comparison.
The CustomConfiguration Propertyindicates that the configuration of the Roleand the assignment of the Roleto Sessionsis vendor specific. Rolesare required to support the RolePermissions Attribute. If a Serverwant to support RolePermissionsbut is not able to support the standard Rolefunctionality, it can indicate this with the CustomConfiguration Property. If CustomConfigurationis TRUE, the Servermay hide the configuration options completely or the Servermay provide additional vendor specific configuration options.
The AddIdentity Methodadds a rule used to map a UserIdentityTokento the Role. If the Serverdoes not allow changes to the mapping rules, then the Method is not present. A Servershould prevent certain rules from being added to particular Roles. For example, a Servershould refuse to allow an ANONYMOUS_5 (see 4.4.2) mapping rule to be added to Roleswith administrator privileges.
The RemoveIdentity Methodremoves a mapping rule used to map a UserIdentityTokento the Role. If the Serverdoes not allow changes to the mapping rules, then the Methodis not present.
The AddApplication Methodadds an ApplicationInstance Certificateto the list of Applications. If the Serverdoes not enforce application restrictions or does not allow changes to the mapping rules for the Rolethe Method is not present.
The RemoveApplication Methodremoves an ApplicationInstance Certificatefrom the list of Applications. If the Serverdoes not enforce application restrictions or does not allow changes to the mapping rules for the Rolethe Methodis not present.
This structure describes an Endpoint. The EndpointTypeis formally defined in Table 5.
Table 5– EndpointType Structure
Name |
Type |
Description |
EndpointType |
structure |
|
endpointUrl |
String |
The URL for the Endpoint. |
securityMode |
MessageSecurityMode |
The type of message security. The type MessageSecurityModetype is defined in OPC 10000-4. The default value is MessageSecurityMode Invalid.The field is ignored for comparison if the default value is set. |
securityPolicyUri |
String |
The URI of the SecurityPolicy. The default value is an empty or null String.The field is ignored for comparison if the default value is set. |
transportProfileUri |
String |
The URI of the Transport Profile. The default value is an empty or null String.The field is ignored for comparison if the default value is set. |
The EndpointType Structurerepresentation in the AddressSpaceis defined in Table 6.
Table 6– EndpointType definition
Attributes |
Value |
|||
BrowseName |
EndpointType |
|||
IsAbstract |
False |
|||
References |
NodeClass |
BrowseName |
IsAbstract |
Description |
Subtype of Structure defined in OPC 10000-5. |
||||
Conformance Units |
||||
Base Info ServerType |
The IdentityMappingRuleTypestructure defines a single rule for selecting a UserIdentityToken. The structure is described in Table 7.
Table 7– IdentityMappingRuleType
Name |
Type |
Description |
IdentityMappingRuleType |
Structure |
Specifies a rule used to map a UserIdentityTokento a Role. |
criteriaType |
Enumeration IdentityCriteriaType |
The type of criteria contained in the identity mapping rule. The IdentityCriteriaTypeis defined in 4.4.4. |
criteria |
String |
The criteria which the UserIdentityTokenmust meet for a Sessionto be mapped to the Role. The meaning of the criteria depends on the criteriaType. The criteriaare a "" for Anonymousand AuthenticatedUser. |
If the criteriaTypeis UserName, the criteriais 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 criteriaTypeis Thumbprint, the criteriais a thumbprint of an immediate user Certificateor an issuer Certificatein its chain which is trusted by the Server. For the criteria, the thumbprint shall be encoded as a hexadecimal string with upper case characters and without spaces.
If the criteriaTypeis Role, the criteriais a name of a restriction found in the Access Token. For example, the Role"subscriber" may only be allowed to access PubSubrelated Nodes.
If the criteriaTypeis GroupId, the criteriais a generic text identifier for a user group specific to the Authorization Service.For example, an Authorization Serviceproviding access to an Active Directory may add one or more Windows Security Groups to the Access Token. OPC 10000-6provides details on how groups are added to Access Tokens.
If the criteriaTypeis Anonymous, the criteriais a null string which indicates no user credentials have been provided.
If the criteriaTypeis AuthenticatedUser, the criteriais a null string which indicates any valid user credentials have been provided.
If the criteriaTypeis Application, the criteriais the ApplicationUrifrom the Client Certificateused for the Session. The Client Certificateshall be trusted by the Serverand the Sessionshall use at least a signed communication channel. This criteria type is used if a Roleshould be granted to a Sessionfor Application Authenticationwith Anonymous UserIdentityToken. If a Roleshould be granted to a Sessionfor Application Authenticationcombined with User Authentication, the Applications Propertyon the RoleTypeis combined with the Identities Propertyon the RoleTypeas defined in 4.4.1.
If the criteriaTypeis X509Subject, the criteria is the X509 subject name of a Certificateof a user which is trusted by the Server. 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 8and 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 8with the lowest number first. Every value from Table 8present in the Certificateshall 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 8contains 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 8that are included in the X509 subject name shall match the content of the criteria String. Names not included in Table 8are ignored.
Table 8– Order for subject name criteria
Order |
Name |
Value |
1 |
CN |
Common Name |
2 |
O |
Organization |
3 |
OU |
Organization Unit |
4 |
DC |
Domain Component |
5 |
L |
Locality |
6 |
S |
State |
7 |
C |
Country |
8 |
dnQualifier |
Distinguished name qualifier |
9 |
serialNumber |
Serial number |
The IdentityMappingRuleType Structurerepresentation in the AddressSpaceis defined in Table 9.
Table 9– IdentityMappingRuleType definition
Attributes |
Value |
|||
BrowseName |
IdentityMappingRuleType |
|||
IsAbstract |
False |
|||
References |
NodeClass |
BrowseName |
IsAbstract |
Description |
Subtype of Structure defined in OPC 10000-5. |
||||
Conformance Units |
||||
Base Info ServerType |
The IdentityCriteriaTypeEnumeration is defined in Table 10.
Table 10– IdentityCriteriaType Values
Name |
Value |
Description |
UserName |
1 |
The rule specifies a UserName from a UserNameIdentityToken. |
Thumbprint |
2 |
The rule specifies the Thumbprintof a user or CA Certificate. |
Role |
3 |
The rule is a Rolespecified in an Access Token. |
GroupId |
4 |
The rule is a user group specified in the Access Token. |
Anonymous |
5 |
The rule specifies Anonymous UserIdentityToken. |
AuthenticatedUser |
6 |
The rule specifies any non Anonymous UserIdentityToken. |
Application |
7 |
The rule specifies an application identity. |
X509Subject |
8 |
The rule specifies the X509 subject name of a user or CA Certificate. |
Its representation in the AddressSpaceis defined in Table 11.
Table 11– IdentityCriteriaType Definition
Attribute |
Value |
|||||
BrowseName |
IdentityCriteriaType |
|||||
IsAbstract |
False |
|||||
References |
NodeClass |
BrowseName |
DataType |
TypeDefinition |
Other |
|
Subtype of the Enumeration type defined in OPC 10000-5 |
||||||
HasProperty |
Variable |
EnumValues |
EnumValueType [] |
PropertyType |
|
|
Conformance Units |
||||||
Base Info ServerType |
This Methodis used to add an identity mapping rule to a Role.
The Clientshall use an encrypted channel and shall provide user credentials with administrator rights when invoking this Methodon 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 Rolebecause of Serverimposed restrictions. |
Bad_NotSupported |
The rule is not supported by the Server. |
Bad_AlreadyExists |
An equivalent rule already exists. |
This Methodis used to remove an identity mapping rule from a Role.
The Clientshall provide user credentials with administrator rights when invoking this Methodon 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 Methodis used to add an application mapping rule to a Role.
The Clientshall provide user credentials with administrator rights when invoking this Methodon the Server.
Signature
AddApplication(
[in]String ApplicationUri
);
Argument |
Description |
ApplicationUri |
The ApplicationUrifor the application. |
Method Result Codes
ResultCode |
Description |
Bad_InvalidArgument |
The ApplicationUriis not valid. |
Bad_RequestNotAllowed |
The mapping cannot be added to the Rolebecause of Serverimposed restrictions. |
Bad_AlreadyExists |
The ApplicationUri is already assigned to the Role. |
Bad_UserAccessDenied |
The session user is not allowed to configure the object. |
This Methodis used to remove an application mapping rule from a Role.
The Clientshall provide user credentials with administrator rights when invoking this Methodon the Server.
Signature
RemoveApplication(
[in]String ApplicationUri
);
Argument |
Description |
ApplicationUri |
The ApplicationUrifor 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 Methodis used to add an endpoint mapping rule to a Role.
The Clientshall provide user credentials with administrator rights when invoking this Methodon 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 Rolebecause of Serverimposed restrictions. |
Bad_AlreadyExists |
The Endpointwith the passed settings is already assigned to the Role. |
Bad_UserAccessDenied |
The session user is not allowed to configure the object. |
This Methodis used to remove an endpoint mapping rule from a Role.
The Clientshall provide user credentials with administrator rights when invoking this Methodon 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. |