The Shared Secret functions leverage the functions described in Operational Functions for Connectors and Management Functions for Utilities. Shared Secret functions are used for storing secret data in a “shared secret” format. These functions provide access to the SecretStore so that the single sign-on information in a user's SecretStore can be shared between different connectors.
To make this possible, the connectors (regular or universal) should conform to the Shared Secret specification, which defines the Shared Secret format as the means by which connectors may share login credentials.
To implement these functions, you should understand the following concepts:
The following terms used with the Shared Secret functions:
Secret: An addressable data member of a user's SecretStore that contains authentication data. Referenced by a SecretID, a secret can contain up to 60 KB of data, though in practice most are much smaller. Secrets are securely encrypted using NICI and the tree and user keys (see Section 1.10, NICI and SecretStore ). Secrets are accessible only to the authenticated NDS/eDirectory user via secure calls to the SecretStore server.
SecretID: An identifier or name by which a data member of SecretStore is referenced. These names are used when reading and writing secrets. They are limited in length to 255 displayable characters encoded in Unicode.
Application: A Windows program, Web application, or mainframe host application for which login information is being stored.
Credential Set: Data used to authenticate a user to a desktop, Web, or host application. Typically comprised of a username and password, a credential set can also include a PIN, e-mail address, domain or database name, certificate, or other information as required by the application. A credential set is also referred to as Login Credentials or Details.
Login Details: The user-friendly name exposed in the user interface and documentation to represent one or more credential sets associated with a given application login.
A shared secret is a regular secret that follows a set of rules that enable it to be read by all connectors that conform to this specification. A shared secret is made up of a type, a name, and a set of key/value pairs. The type and name of a shared secret combine to form the shared secret's identifier (secretID); the set of key/value pairs make up the data.
NOTE:The Shared Secret specification identifies certain reserved characters that must be escaped when used outside of their context. See the list of Reserved Characters.
The following format should be used for the SecretIDs to comply with the Shared Secret format:
<type>:<name>
where <type> identifies the type of shared secret (either “SS_App” for Application secrets or “SS_CredSet” for Credential Set secrets), and <name> identifies the name of the shared secret.
The colon ( : ) serves as a delimiter and should not be escaped. All reserved characters used in either the type or name must be escaped. When combined, the type, colon, and name string cannot exceed 255 displayable characters in length.
Shared Secret data is made up of key/value pairs in the following format:
<key><delimiter><value><linefeed>...<key><delimiter><value><linefeed><null>
where <key> identifies a key, <delimiter> is the equals character ( = ) in most cases (otherwise the colon character), <value> identifies a value, <linefeed> is the line feed character, and <null> is the null terminator that must always appear at the end of the data.
Line feed characters separate the pairs from each other. All of the pairs combined cannot exceed 60 KB in size. Keys should be treated as case-ignore strings, whereas the values are case sensitive. A null terminator must follow the last pair to signal the end of the sequence. The null terminator must be present even when no entry exists. Duplicate keys are not allowed; however, duplicate values are permitted and should be discarded by connectors if they are encountered during parsing operations. The data must be in 16-bit Little Endian Unicode*, including the null terminator. All reserved characters used in the key or value must be escaped.
In processing, be careful to modify only those key/value pairs on which the connector is directly dependent. For example, suppose you have two connectors that are dependent on the same shared secret, but one uses a Password key whereas the other requires a PIN key. In such a case, each application should add its own key without modifying any of the other keys that may exist but are not required for its operations.
The following are Shared Secret reserved characters:
Reserved characters that are used outside of their context must be escaped by preceding them with a backslash ( \ ) character.
NOTE:Line feed and null characters cannot be used within a character string.
There are currently two types of shared secrets:
When used together, these types of shared secrets can enable several applications to use the same set of credentials, or enable one application to have more than one set of credentials. This effectively means that, depending on the connector's choosing, there can be a many-to-many relationship between the two types.
As indicated in the example earlier, different connectors might, as allowed by the target application, require different credentials for authenticating the users (password, smart card, PIN, etc.). This results in the need for a many-to-many grouping of these secrets.
Application shared secrets are used to represent Windows applications, Web applications, or mainframe/host applications. Application SecretIDs follow the previously defined format with a type value of SS_App. The application ID should be able to uniquely identify the application. As a rule, it should use the appropriate format as shown in the following table:
|
Application Data Type |
Application Format |
|---|---|
|
Windows |
program_name.exe |
|
Web |
unique URL |
|
Mainframe/host |
host application name |
Application data contains application-specific information that is necessary to authenticate the user to the application but is not considered a credential. Examples include the Control ID for a password field in a Windows application, or the name of a password field in a Web form.
Users do not normally need to enter such information to authenticate; it is inherent in the application. This application-specific data is in the key/value pair format with an equals ( = ) character as the delimiter. The choice of what keys to use is left up to the connector.
Application data also contains pointers to the credential sets with which the application is associated. These pointers follow the key/value pair format as follows:
SS_CredSet:<credsetname>
where <credsetname> is the name of the credential set that is associated with the application.The key must be SS_CredSet and the colon character serves as the delimiter for credential set pointers.
NOTE:An exception to the data format for these pointers is that duplicates are permitted when the key is SS_CredSet to enable applications to be associated with more than one credential set.
Credential Set shared secrets are used to contain login credentials needed to authenticate a user to a Windows application, Web site, or mainframe/host application. They can be shared between multiple applications of the same or different type, primarily when the authentication database or mechanism behind such applications is the same.
Examples include NDS authentication to the same object in a tree, or Windows and Web interfaces to the same application, such as GroupWise. By sharing credential sets, a password saved or changed in one application automatically applies to other applications that share the same authentication database and secret data at the target.
Credential Set SecretIDs follow the format outlined previously with a type value of SS_CredSet. The administrator or user normally determines the name of a credential set. The name should help associate shared credentials with the appropriate applications. An example of a shared secret identifier is:
SS_CredSet:Groupwise
Credential data contains information that users provide to authenticate to an application. Examples include the username and the password. This data is in the key/value pair format, with an equals character ( = ) as the delimiter. The choice of which keys to use is left up to connector. However, connectors must agree with each other on this to share single sign-on information. Thus, where possible, the following known keys should be used:
An example of a shared secret value is:
Password=zuma<linefeed>Username=jdoe<null>