ActiveRoles/[$roleID] GET

This page documents the format and semantics of the response message that the Otis Service sends in response to a query for active roles in an authenticated session.

Notational Conventions

• Variables are represented using a $variable notation. For example, the $HostName variable represents a server host name. An actual value for $HostName might be something like "code.bandit-project.org".
• Characters are appended to elements and attributes to indicate cardinality:
  • "?" (0 or 1)
  • "*" (0 or more)
  • "+" (1 or more)
• The character "|" is used to indicate a choice between alternatives.
• Items contained in braces ("{" and "}") are used to indicate that contained items are to be treated as a group.

Request Noun URL

The following URL is the "noun" that is used to query active roles within an authenticated session:

http://$HostName/$OtisAppName/AuthenticatedSession/$sessionID/ActiveRoles{{{/[$roleID]}}}

For example, to query ALL of the active roles for a session:

http://code.bandit-project.org/otis/AuthenticatedSession/78BD660E0E5F673378BD660E0E5F6733/ActiveRoles

or, to determine if a specific role is currently active in the session:

http://code.bandit-project.org/otis/AuthenticatedSession/78BD660E0E5F673378BD660E0E5F6733/ActiveRoles/Admin_Role

Session Secret

When a session is first created, the OTIS server may assign a secret to the session. Whether or not a session secret is created depends on a setting in the OTIS server called SessionSecretBitSize. See here for documentation on this setting. If a size of zero is specified, no session secret will be created. If a session secret is created, it will be returned to the client in the first response message the OTIS server sends back to the client during authentication. For more detail on this response, see here. Thereafter, the client is expected to send the secret in an HTTP header called SessionSecret whenever it wants to perform actions on the session. If the session secret is not provided, or does not match the one OTIS has for the session, the request will be rejected. NOTE: The header is NOT required if no session secret has been generated by OTIS (SessionSecretBitSize == 0).

Response Message Format

If the query for active roles fails, the HTTP response code will contain an error code, and the content of the response will contain additional information. For more information on error responses, see here. Otherwise, the content of the query response message for a session's active roles is as follows:

<otis:AuthSession xmlns:otis="http://code.bandit-project.org/schemas/2008/otis">
   <otis:sessionURL>${sessionURL}</otis:sessionURL> ?
   <otis:RoleList> ?
      <otis:Role> +
         <otis:RoleID isInRole="$isInRole">$roleID</otis:RoleID>
         <otis:RoleDescription>$roleDescription</otis:RoleDescription> ?
         <otis:RoleName>$roleName</otis:RoleName> ?
         <otis:Property Name="$propertyName" Type="$propertyType"> *
            <otis:PropertyValue>$propertyValue</otis:PropertyValue> +
         </otis:Property>
      </otis:Role>
   </otis:RoleList>
</otis:AuthSession>

Response Elements and Attributes

• otis:AuthSession element. This is always the root element for the response message.
• otis:sessionURL element. This is an optional element which, if present, contains the URL (in the $sessionURL variable) for this authenticated session.
• otis:RoleList element. This element contains a list of otis:Role child elements. If it is missing, there were no active roles for the authenticated session. If a $roleID variable was specified in the URL after the "ActiveRoles" sub-noun, it is the only role that will be reported in the response message. In that case, if the otis:RoleList element is missing, it means that the specified role is neither an active role or an assumeable role.
• otis:Role. There is an otis:Role element for every active role in the authenticated session. If a $roleID variable was specified in the URL after the "ActiveRoles" sub-noun, there will only be one otis:Role element - one for the role specified by $roleID.
• otis:RoleID. This is a required element. It holds the role's ID (specified in the $roleID variable).
• isInRole attribute. This attribute on the otis:RoleID element specifies whether the role is a currently active role for the authenticated session. The $isInRole variable will contain a value of "true" or "false"
• otis:RoleDescription element. This is an optional element. If present, it contains a description for the role (specified in the $roleDescription variable).
• otis:RoleName element. This is an optional element. If present, it contains a displayable name for the role (specified in the $roleName variable).
• otis:Property element. There may be zero or more otis:Property elements. These contain additional role properties. The name of the property is specified in the Name attribute (the $propertyName variable), and the data type of the property is specified in the Type attribute (the $propertyType variable). The property's value(s) are held in the otis:PropertyValue child elements.
• Name attribute. This attribute on the otis:Property element contains the name of the property (specified in the $propertyName variable). This name should be unique.
• Type attribute. This attribute on the otis:Property element contains the data type of the property (specified in the $propertyType variable). Valid property types are as follows:
  • Map. All otis:PropertyValue elements contain one or more nested otis:Property elements. This is how a complex type is specified.
  • string. All otis:PropertyValue elements contain string values - which is basically anything.
  • normalizedString. Same as string.
  • int. All otis:PropertyValue elements contain integer values. The range of allowed values is the same as for the Java int scalar type.
  • long. All otis:PropertyValue elements contain integer values. The range of allowed values is the same as for the Java long scalar type.
  • short. All otis:PropertyValue elements contain integer values. The range of allowed values is the same as for the Java short scalar type.
  • byte. All otis:PropertyValue elements contain integer values. The range of allowed values is the same as for the Java byte scalar type.
  • boolean. All otis:PropertyValue elements contain a boolean value of either "true" or "false".
  • float. All otis:PropertyValue elements contain floating point values. The range of allowed values is the same as for the Java float type.
  • double. All otis:PropertyValue elements contain floating point values. The range of allowed values is the same as for the Java double type.
  • base64Binary. All otis:PropertyValue elements contain a base 64 encoded value. This base 64 encoded value represents a Java byte array (byte[]) type.
  • anyURI. All otis:PropertyValue elements contain a valid URI. This value must be convertible to a Java java.net.URI type.
  • dateTime. All otis:PropertyValue elements contain a valid date-time value. This value must be convertible to a Java java.util.Date type. The following date formats are allowed:
    • yyyy-MM-dd'T'HH:mm:ss.S'Z': 1983-01-31T23:11:01.978Z
    • yyyy-MM-dd'T'HH:mm:ss'Z': 1983-01-31T23:11:01Z
    • yyyy-MM-dd'T'HH:mm:ss.SZ: 1983-01-31T23:11:01.978-0700
    • yyyy-MM-dd'T'HH:mm:ssZ: 1983-01-31T23:11:01-0700
    • yyyy-MM-dd: 1983-01-31
    • MM/dd/yy: 01/31/83
    • MM/dd/yyyy: 01/31/1983
    • MMMMMMM d, yyyy: January 31, 1983
    • MMM d, yyyy: Jan 31, 1983
    • EEE, d MMM yyyy: Mon, 31 Jan 1983
    • EEE, MMM d, yyyy: Mon, Jan 31, 1983
    • EEE, MMMMMMM d, yyyy: Mon, January 31, 1983
    • EEE, d MMMMMMM yyyy: Mon, 31 January 1983
      The following time formats may be combined with the formats above that do not already have a time component:
    • h a: 11 pm
    • h:mm a: 11:11 pm
    • h:mm:ss a: 11:11:01 pm
    • H: 23
    • HH:mm: 23:11
    • HH:mm:ss: 23:11:01
    • HH:mm:ss Z: 23:11:01 -0700
• otis:PropertyValue element. This element holds a value for the property (contained in the $propertyValue variable). A property with multiple values will have multiple otis:PropertyValue elements. Note that the $propertyValue variable can be a list of nested otis:Property elements. Complex properties would be represented by nesting otis:Property elements.