Purpose and Scope

User Service provides applications and other services (henceforth "consumers") with:

1. federated identity services within the nGen Platform,
2. single sign-on and sign-out, and
3. shared user profiles across consumers

Terminology

User Service uses the following terminology:

• Consumer - any application or service interacting with the nGen Platform.
• BSG RA GUID- aka nGen Reference Architecture Globally Unique Identifier. A unique string that identifies each consumer. BSG RA GUIDs have the form: 6b0c73c0-bsga-kali-rome-001b7744e04a. In the Ruby language you can produce a similarly formatted identifier using the UUIDTOOLS library command: UUID.timestamp_create().to_s.
• SLO/SSO - Single Log On and Single Log Out. A way to share a single login across multiple applications
• SAML - Security Assertion Markup Language. A way to verify accuracy and ownership of a document containing user profile data.
• Profile/Persona/User- an interchangeable term used to describe the user and their persona/profile(s) managed by the User Service.

Conventions and Return Codes

The API supports the nGen Platform conventions:

• Bad Request failures (e.g. supplying the wrong input parameters) will return HTTP code 400
• Authorization failures (e.g. using unknown user credentials) will return HTTP code 401
• Forbidden User (e.g. a user that has been banned) will return HTTP code 403
• Item Not Found failures (e.g. supplying an id for missing data) will return HTTP code 404
• Unsupported Service Invocations (e.g. using unsupported verbs or requesting an unsupported format - .xml/.html/etc) returns HTTP code 405
• Conflict failures (e.g. email already exists when attempting to create user) will return HTTP code 409
• Unsupported Media Type failures (e.g. supplying non-xml format for service that expects xml) will return HTTP code 415
• Internal Errors and other exceptions will return HTTP code 500
• As a general guideline, nGen Platforms services return appropriate HTTP codes wherever possible.

API

All methods in the API require a bsgra_guid value appropriate to your consumer service be passed in as either an HTTP header named 'BSGRA_GUID' or as an HTML parameter name 'bsgra_guid'.

Accounts Resource

This resource handles Single-Sign-On(SSO) and Single-Log-Out (SLO)

• GET /accounts/login.html?SAMLRequest=<valid_saml_request>
  Initiates a SAML SSO (Single Sign On) request. The SAMLRequest query string parameter is expected to be ZLib Deflated, Base64 encoded and CGI/URI escaped (in that order). An example SAML request is show below (before aforementioned 'packing' of the SAML).
  

  <?xml version='1.0' encoding='UTF-8'?>
  <samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    ID="5256BD37BC438FE781C0E0D862A6BF2FE6B1FF2427"
    Version='2.0'
    IssueInstant="2007-12-04T19:40:54Z"
    ProtocolBinding="urn:oasis:names.tc:SAML:2.0:bindings:HTTP-Redirect"
    ProviderName="localhost:3000"
    AssertionConsumerServiceURL="http://www.kalivo.com/account/acs">
  </samlp:AuthnRequest>

  • Bad Request: 400, in the event of an invalid or missing 'SAMLRequest' parameter.
  • Method Not Allowed: 405, in the event of any format request other than HTML.
  • Success: 200. A login page is displayed.
• POST /accounts.html OR /accounts.xml
  The expected parameters are different based on the format (html or xml). Resource output is identical for either.
  • HTML: Next step after GET /accounts/login for browser based authentication and login
    email: Email of user attempting to login
    password: Password of above user
    SAMLRequest: Valid SAML request (same as for GET /accounts/login resource)
  • XML: To retrieve an existing SAML response (verification of a SAML token)
    auth_session_index: The SessionIndex attribute value of an AuthnStatement element from a SAML token. For a given a SAML response token, you must pull the SessionIndex attribute value and pass it as a parameter.
  • Bad Request: 400, in the event of an invalid or missing 'SAMLRequest' parameter.
  • Forbidden: 403, in the event a user has been banned.
  • Success: 200. Note that the response body is a SAML Response, which may or may not indicate success. The 'Value' attribute of the 'samlp:StatusCode' element must be parsed from the response. A value of 'urn:oasis:names:tc:SAML:2.0:status:Success' indicates success, any other value indicates an invalid SAML token.
    A valid SAML XML response body follows:

    <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="04CD1D20CC6CDBE71CAFED08406CB4E2BF77872C64" IssueInstant="2007-12-10T16:51:02Z" Version="2.0">
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></ds:CanonicalizationMethod>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
        <ds:Reference URI="">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
            <ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></ds:Transform>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
          <ds:DigestValue>b5Nrptqa5oj2V8eKH8yZ8zbT3Bg=</ds:DigestValue>
        </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
          QX6S3fGmpbSO3KfxY9mJQT7af/EUAdPA07ww156p2U9oGTrpsAZUHcHPC8OZyc0EU3MdUUETMAV71oTNLfPHhWVpD6z1k/iJLA5CEMCGmHYzh8dtnoL6g/lJ/cewYEXrf7ZQo/rYUrmI51CSoopG4rUXPt7pUmbCCPafr1V9yxY=</ds:SignatureValue>
        <ds:KeyInfo>
          <ds:KeyValue>
            <ds:RSAKeyValue>
              <ds:Modulus>REE4NTREQ0QzRDBGMjhFNzU1MjY1NzM0RDA2NDQxNkNENkNFNjQ0NTE3RTA0
              QkQ0MDYzMkQ2M0FGQzFGQTRFN0Y4QzA2OThBOUNCOTkwODNEMjEyQTkwRDMy
              NjMzOTNBMzY5MDAyOUJDNzUxQTQ5M0I5RDcyQUU2MjJFRkNBQTk4MEM4RjA5
              RjIzMzQxRDJDQUIzNDQ4N0I0MkQwQkQ3NDIxNkM2NTUxMzM2RkI5RERDQjhF
              MDFDMDhFMTM4ODQ2MTVEQkRCNTQxMTNFNTEyQTAxOUNFOEQ1NTdEQkJGQjI3
              ODUyRDJDNjM0QzAzQzY0OUY5RkEyRkQxNDJGMjgwOQ==
              </ds:Modulus>
              <ds:Exponent>AQAB</ds:Exponent>
            </ds:RSAKeyValue>
            </ds:KeyValue>
          </ds:KeyInfo>
        </ds:Signature>
    <samlp:Status>
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"></samlp:StatusCode>
    </samlp:Status>
    <Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion" ID="833A46F68D5787087C0131EAA01542BBC56FD52868" IssueInstant="2003-04-17T00:46:02Z" Version="2.0">
      <Issuer></Issuer>
      <Subject>
        <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">45038c42-a2d6-11dc-88e1-0019d1039198</NameID>
        <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"></SubjectConfirmation>
      </Subject>
      <Conditions NotBefore="2007-12-10T16:51:02Z" NotOnOrAfter="2007-12-17T16:51:02Z"></Conditions>
      <AuthnStatement AuthnInstant="2007-12-10T16:51:02Z" SessionIndex="22d45caf13610fc9f2c44f249361a8a7">
        <AuthnContext>
          <AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</AuthnContextClassRef>
        </AuthnContext>
      </AuthnStatement>
      <AttributeStatement>
        <Attribute>
          <AttributeValue>
            <user>
              <banned>true</banned>
              <created_at>2007-12-04T21:32:56-06:00</created_at>
              <email>tech-support@kalivo.com</email>
              <guid>45038c42-a2d6-11dc-88e1-0019d1039198</guid>
              <updated_at>2007-12-09T15:30:04-06:00</updated_at>
              <active_persona>
                <company_name>Kalivo</company_name>
                <created_at>2007-12-04T21:32:57-06:00</created_at>
                <display_name>Kalivo Support</display_name>
                <full_name></full_name>
                <ip></ip>
                <job_title></job_title>
                <updated_at>2007-12-04T21:32:57-06:00</updated_at>
                <uri>http://www.kalivo.com</uri>
              </active_persona>
            </user>
          </AttributeValue>
        </Attribute>
      </AttributeStatement>
      </Assertion>
    </samlp:Response>

    An invalid SAML XML response body follows:

    <samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" ID="A37632061F57E704A474B43B4F0BD446DE3DD34F04" IssueInstant="2007-12-13T13:18:57Z" Version="2.0">
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
      <ds:SignedInfo>
        <ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></ds:CanonicalizationMethod>
        <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
        <ds:Reference URI="">
          <ds:Transforms>
            <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
            <ds:Transform Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315"></ds:Transform>
          </ds:Transforms>
          <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
          <ds:DigestValue>qKxBT+JuEBR9Q/StJwnewXhsnoI=</ds:DigestValue>
        </ds:Reference>
      </ds:SignedInfo>
      <ds:SignatureValue>QZWbYo1D9Ej3MNHFW4NZsYq4kJ8zuSep03q9m1uEb4HjmjZjfAChg8KeIK9T
        FLKaFP+K5fPzlYfQeBEBhCa8MbNJ8sT58P87uzIQodxgKKPKahB8su3XiczN
        BWCXp4g5zZ/7plzHZeID0kPYS+I5vs+bpP9hAZIiXqVF73yKXuY=
      </ds:SignatureValue>
      <ds:KeyInfo>
        <ds:KeyValue>
          <ds:RSAKeyValue>
            <ds:Modulus>REE4NTREQ0QzRDBGMjhFNzU1MjY1NzM0RDA2NDQxNkNENkNFNjQ0NTE3RTA0
              QkQ0MDYzMkQ2M0FGQzFGQTRFN0Y4QzA2OThBOUNCOTkwODNEMjEyQTkwRDMy
              NjMzOTNBMzY5MDAyOUJDNzUxQTQ5M0I5RDcyQUU2MjJFRkNBQTk4MEM4RjA5
              RjIzMzQxRDJDQUIzNDQ4N0I0MkQwQkQ3NDIxNkM2NTUxMzM2RkI5RERDQjhF
              MDFDMDhFMTM4ODQ2MTVEQkRCNTQxMTNFNTEyQTAxOUNFOEQ1NTdEQkJGQjI3
              ODUyRDJDNjM0QzAzQzY0OUY5RkEyRkQxNDJGMjgwOQ==
            </ds:Modulus>
            <ds:Exponent>AQAB</ds:Exponent>
          </ds:RSAKeyValue>
        </ds:KeyValue>
      </ds:KeyInfo>
      </ds:Signature>
    <samlp:Status>
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed"></samlp:StatusCode>
    </samlp:Status>
    </samlp:Response>

• DELETE /accounts/login.html?SAMLRequest=<valid_saml_request>
  NOTE: This is not yet fully implemented
  Initiates a SAML SLO (Single Log Out) request. The SAMLRequest query string parameter is expected to be ZLib Deflated, Base64 encoded and CGI/URI escaped (in that order). This request will initiate a series of logouts to every application that the user has logged into through the accounts resource. An example SAML Logout request is show below (before aforementioned 'packing' of the SAML).
  

  <samlp:LogoutRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    ID="5256BD37BC438FE781C0E0D862A6BF2FE6B1FF2427" Version="2.0"
    IssueInstant="2007-12-04T19:40:54Z">
      <Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        http://idp.com
      </Issuer>
      <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
        27213a00-ab4e-11dc-b05d-0019b9788c02
      </NameID>
      <samlp:SessionIndex xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
        527a5a7f5c9fde59757447a6890aa174
      </samlp:SessionIndex>
  </samlp:LogoutRequest>

  • Bad Request: 400, in the event of an invalid or missing 'SAMLRequest' parameter.
  • Success: 200. The expected XML response body:

    ???

User Resource

User data (profile/personas) resource.

• GET users/<user_guid>.xml?auth_session_index=<authorized_session_index[optional]>
  Returns the XML representation of the user that has a matching guid or MD5 hash of their email address.
  • 404, if no user is found from the user_guid parameter.
  • 200 and a public profile, if the user is found and the authorized_session_index either isn't provided or doesn't match the user being requested, and the user is not an admin user
  • A public profile sample body follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <active_persona>
        <company_name>Kalivo</company_name>
        <display_name>Mike Roeder</display_name>
        <full_name>Mike Roeder</full_name>
        <job_title>Professional Wrestler</job_title>
      </active_persona>
    </user>

  • 200 and a full profile, if the user is found and the authorized_session_index is provided and matches that of the user being requested, or the user of the authorized_session_index is an admin
  • A full profile sample response body follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <user>
      <created_at>2007-10-30T12:22:23-05:00</created_at>
      <email>mike@roeder.com</email>
      <guid>bd583a30-870c-11dc-b10e-7a79056e579e</guid>
      <updated_at>2007-10-30T12:22:23-05:00</updated_at>
      <active_persona>
        <company_name>Kalivo</company_name>
        <created_at>2007-10-30T12:22:23-05:00</created_at>
        <display_name>Mike Roeder</display_name>
        <full_name></full_name>
        <ip></ip>
        <job_title></job_title>
        <updated_at>2007-10-30T12:22:23-05:00</updated_at>
        <uri>http://www.kalivo.com</uri>
      </active_persona>
    </user>

• GET users/new.html?SignupRequest=<signup_request>&RelayState=<relay_state>
  Returns the HTML form for creating a new user. A valid, base64 encoded signup_request is required (example follows). Relay state will be carried through the call if it exists. Note: The 'addtional' fields (OptionalAdditionalFields, RequiredAdditionalFields, PublicAdditionalFields) are optional and allow for custom fields to be applied to the signup form, saved and returned to the caller.
  Example signup request:
  

  <?xml version="1.0" encoding="UTF-8"?>
  <SignupRequest ID="[[ID]]"
    Version="1.0"
    IssueInstant="[[ISSUE_INSTANT]]"
    ProviderName="[[DOMAIN]]"
    AssertionConsumerServiceURL="[[ACS_URL]]"
    RequiredFields="[[REQUIRED_FIELDS]]"
    OptionalAdditionalFields="[[OPTIONAL_ADDITIONAL_FIELDS]]"
    RequiredAdditionalFields="[[REQUIRED_ADDITIONAL_FIELDS]]"
    PublicAdditionalFields="[[PUBLIC_ADDITIONAL_FIELDS]]">
  </SignupRequest>

  
  
• GET users/<user_guid>.html?ProfileRequest=<profile_request>&RelayState=<relay_state>
  Returns the HTML form for creating editing a user. A valid, base64 encoded profile_request is required (example follows). Relay state will be carried through the call if it exists. Note: The 'addtional' fields (OptionalAdditionalFields, RequiredAdditionalFields, PublicAdditionalFields) are optional and allow for custom fields to be applied to the edit form, saved and returned to the caller.
  Example profile request:
  

  <?xml version="1.0" encoding="UTF-8"?>
  <ProfileRequest ID="[[ID]]"
    Version="1.0"
    IssueInstant="[[ISSUE_INSTANT]]"
    ProviderName="[[DOMAIN]]"
    AssertionConsumerServiceURL="[[ACS_URL]]"
    RequiredFields="[[REQUIRED_FIELDS]]"
    OptionalAdditionalFields="[[OPTIONAL_ADDITIONAL_FIELDS]]"
    RequiredAdditionalFields="[[REQUIRED_ADDITIONAL_FIELDS]]"
    PublicAdditionalFields="[[PUBLIC_ADDITIONAL_FIELDS]]">
  </ProfileRequest>

  
  
• POST /users.xml
  Create a new user, from a passed in block of user xml. Parameter name for the xml is 'user'. An example format follows:
  

  <?xml version="1.0" encoding="UTF-8"?>
  <user>
  <salt>8b75c8ca42a99fce66f1cb6b6a9b7837bae79cee</salt>
    <last_login_at>2006-08-10T17:03:44-05:00</last_login_at>
    <job_title></job_title>
    <uri>http://www.kalivo.com</uri>
    <updated_at>2006-06-12T20:15:45-05:00</updated_at>
    <is_banned>false</is_banned>
    <activated_at>2006-05-31T02:34:42-05:00</activated_at>
    <guid>52b6bd50-897c-11dc-8517-0019b9788c02</guid>
    <crypted_password>91dada54971e43614a12208af18992f2248c3aeb</crypted_password>
    <company_name>Kalivo, Inc.</company_name>
    <yahoo_name></yahoo_name>
    <previous_last_login_at>2006-06-12T15:54:50-05:00</previous_last_login_at>
    <num_of_logins>4</num_of_logins>
    <activation_code></activation_code>
    <rank>Member</rank>
    <password_reset_code></password_reset_code>
    <id>2</id>
    <immutable>false</immutable>
    <ip></ip>
    <has_avatar>false</has_avatar>
    <display_name>Brittain</display_name>
    <full_name></full_name>
    <deletable>true</deletable>
    <email>scott_brittain@hotmail.com</email>
    <password>test</password>
    <created_at>2006-05-30T21:34:40-05:00</created_at>
  </user>

  Note that you can pass any arbitrary user attributes to the users.xml resource and they will be stored. However, email, password and display_name are required.
  • Bad Request: 400, in the event the user could not be created. The user xml with error elements will be returned.
  • Unsupported Media Type: 415, in the event that invalid xml or no xml passed to resource
  • Success: 200. The expected XML response body is the same as for the GET /users resource
• PUT /users/<user_guid>.xml
  Updates a given user from a passed in block of user xml. Parameter name for the xml is 'user'. The format is similar to that for creating a user except that there are only two required elements - email and display_name.
  • Bad Request: 400, in the event the user could not be created.
  • Not Found: 404, in the event the user could not be found by their email hash.
  • Conflict: 409, in the event the it was discovered that the user was attempting to change their email to an already existing email address in the system.
  • Unsupported Media Type: 415, in the event that invalid xml or no xml passed to resource.
  • Success: 200. The expected XML response body is the same as when creating a user, above.

Password Reset Resource

User resource for resetting a user password.

• POST /password_reset/<user_guid>.xml
  For a user with the given guid, this resource will create and return a password reset code that you must use to reset the password
  • 400, in the event that the password reset code cannot be created.
  • 404, in the event that the user can not be found.
  • Success: 200. A sample response body follows:

    <password_reset_code>abcdefg123456789</password_reset_code>

• PUT /password_reset/<password_reset_code>.xml
  For the user with the given password_reset_code (initially set and retrieved by the POST method), reset their password to the given value. You are expected to pass 2 parameters, 'password' and 'password_confirmation'. They must be equal.
  • 400, in the event that no password is given, or that the password and confirmation do not match.
  • 404, in the event that the user with the given password_reset_code can not be found.
  • 500, in the event that the password can not be reset
  • Success: 200.

Activation Resource

User resource for activating a new user. After a user is created, they must be activated before they can be logged in.

• POST /activation.xml
  Send an email to the user with their activation notice, and return the activation code. Expects the user guid or email as parameters in the Request body. Either one or both can be specified.
  • id: This is the parameter name for specifying the guid value of the user.
  • email: This is the parameter name for specifying the email of the user.
  • A sample request body follows:

  email=arahim@ngenera.com

  • Success: 200. A sample response body follows:

    <activation_code>abcdef123456789</activation_code>

  • 400, in the event that the user has already been activated.
  • 404, in the event that the user can not be found.
• GET /activation/<activation_code>.xml
  Activate a user with the given activation_code (retrieved from the POST method, above).
  • 404, in the event that the user can not be found.
  • Success: 200. An XML representation of the user is returned (See the User Resource section for examples)

User Import Resource

This resource is for batch uploading users.

• POST /user_imports.xml
  Batch import org-chart data, from a passed-in block of xml. Parameter name for the xml is 'org'. For each record in the import, two relations will be created in the org service - a 'Reports To' relation and a 'Supervisor Of' relation. Expected format follows:
  

  
  <Root>
    <EmployeeInfo>
      <FirstName>JOHN</FirstName>
      <LastName>SMITH</LastName>
      <Manager>FRANKLIN, ROBERT</Manager>
    </EmployeeInfo>
    <EmployeeInfo>
      <FirstName>PETER</FirstName>
      <LastName>SMITH</LastName>
      <Manager>GOLDBERG, SIMON</Manager>
    </EmployeeInfo>
  </Root>

  • Bad Request: 400, in the event of an invalid 'org' parameter.
  • Success: 200. Returns:

    
    <results>
      <message>Error Message (repeating, if any)</message>
      <success># of successful imports</success>
      <fail># of failed imports</fail>
    </results>

© Copyright 2006-2009 nGenera Corporation - All rights reserved. Version 2.6.3