Creating Accounts and Users

Authors: Stephanie Groot, Neustar; Jim Taylor and Albert Koval, DECE

This article explains how to create new Accounts and Users and recommends practices for a simple user experience.

To streamline entry into the UltraViolet ecosystem, certain Nodes (Retailers, LASPs<, and Access Portals) can provide a custom interface to help users easily create a new UltraViolet Account and User. This can happen at the same time the user is signing up for a new account at the Node's own service, or can be offered to users who already have an account at the Node.

See IUX Best Practices for additional guidelines on how to design account creation and account linking user interfaces.

Requirements and Options

Minimum user data that must be provided:

Country (can be prefilled from geolocation or Node's country of operation)
First and Last Name^*
Email address
Username (can substitute email address)
Account display name (can substitute user's last name)

Optional data

Password (if omitted, Coordinator will generate a random password)
User preferred language (if omitted, Coordinator will use language of Country, e.g., en-US, en-GB, en-CA)
(Other user data such as image, mobile phone, email verification)
Terms of Use acceptance ³ (if not included, user will not be able to use ecosystem until accepting TOU at Web Portal or Node)

Obsolete elements:

Date of birth is no longer collected.
Consent to link accounts (UserLinkConsent) is now automatic and no longer needs to be collected from the User or submitted to the Coordinator.
Consent for licensee to engage in marketing/recommendations (UserDataUsage) no longer needs to be submitted to the Coordinator. Licensee should continue to obtain consent from the user in compliance with local regulations.
Consent to provide account management (ManageUserConsent and ManageAccountConsent) is no longer needs to be collected from the User or submitted to the Coordinator. Implementers who wish to provide Account Management services (such as password change, user delete, email change, etc.) must submit a request to DECE and qualify to obtain access.

*Last name required as of Coordinator 1.0.4 (July 2012)

Flow for Creating an Account and Initial User

If creating a new UV Account and User from an existing user in your system
- Check if e-mail address or username is already in use in UltraViolet (using ResourcePropertyQuery API)*
- If e-mail or username matches, notify the user and give them the opportunity to link to their existing UltraViolet account (see DSecMech 5.5)
  - Either present the UltraViolet authentication form or get user consent to use InstaLink. (See Authentication UI and InstaLink.)
- If e-mail and username don't match, clearly inform the user that an UltraViolet account will be created for them
  - Show the UltraViolet logo (with a hyperlink to uvvu.com).
  - Preferrably provide a "What is UltraViolet" link to more information. See Compliance Rules and Messaging Requirements for required/recommended text.
  - Provide a checkbox for Terms of Use (TOU) and Privacy Policy (PP) acceptance from the user¹ (see DGeo 2.6.1). Use DECE-supplied language from DGeo and link to TOU/Privacy Policy document for Country.
  - Provide a checkbox for the user to agree to create and link accounts (see DSecMech 5.5). Use DECE-supplied language from Compliance Rules.
If creating a new UV Account and User at the same time as creating a new user in your system
- Show UI for account creation
  - Get First name, Last name, email address from user
    - May collect password (or omit to have Coordinator generate random password)*
    - May collect username (or use email address instead)
    - May collect account display name (or use last name instead)
    - Should test for an existing user associated with the provided email address by calling ResourcePropertyQuery ²
      - If email matches, recommend the user link to their existing UltraViolet account. See above.
    - Should test if the username is available by calling ResourcePropertyQuery ²
  - Must use DECE-supplied language in Compliance Rules related to account creation and user consent to link accounts
  - May collect TOU acceptance (must use acceptance text from Geographies spec, must link to TOU/Privacy Policy document for Country)
To create the Account and User
- Call AccountUserCreate()
  - Supply Account DisplayName and Account Country (e.g., "US" or "GB")
  - Set UserClass to FAU
  - Supply PrimaryEmail, Credentials (Username, Password), GivenName, Surname, and other optional elements
    - Best not to set User Languages; Coordinator sets automatically based on User's country setting ²
  - Include TermsOfUse policy request
    - Resolve the TOU URL by GETting the well-known TOU URL. (See Collecting Terms Of Use.)
  - Coordinator returns URL of User resource
- Call STS (within 15 minutes)
  - Exchange credentials (username and password, unless password was omitted during User creation) for Security Token
  - Coordinator returns Delegation Security Token (DST)
  - GET an assertion on the Security Token resource

*Feature added in Coordinator 1.0.4 (July 2012)

¹Feature added in Coordinator 1.0.4 (July 2012)

²Feature added in Coordinator 1.0.5 (October 2012)

³Node collection of TOU acceptance first allowed in Coordinator 1.0.4 (July 2012)

See the Account creation pseudo code below

More Information

For more on Account linking, see Linking and Security Tokens.

Examples:

/*
resource property query status:
300 Multiple Choices – the search matched more than one resource. No disambiguation information will be provided.
 This will only be returned for queries targeting PrimaryEmail, and only if the email address is associated with more than one account.
302 Found - the search matched an existing entry for the targeted resource type.
400 Bad Request - the XPath expression is not valid, or the request cannot otherwise be fulfilled.
403 Forbidden - the Node is not allowed to perform this request.
404 Not Found – the search did not yield any match.
*/

/* within new account submission form */

/* check if email already in use in UltraViolet */
on form.email_address.update {
        if(dcoord.resourcepropertyquery(PrimaryEmail, form.email_address).status == 300|302){
                /* email already registered.
                   prompt user "Looks like you already have an UltraViolet account, please sign in; or
continue to create a new UltraViolet account." */
        }elseif(dcoord.resourcepropertyquery(PrimaryEmail, form.email_address).status == 404){
                /* email not in use, no action (or show an "input accepted" icon next to field) */
        }else{
                /* handle error */
        }
}

/* check if username available */
on form.username.update {
        if (dcoord.resourcepropertyquery(Username, form.username).status == 302){
                /* prompt user for different username or offer option to sign in to UltraViolet */
        }elseif (dcoord.resourcepropertyquery(Username, form.username).status == 404){
                /* the username is available, no action (or show an "input accepted" icon next to field) */
        }else{
                /* handle error */
        }
}


user = create(
        DisplayName = Smith Household,
        Country = US;
        Username = timmy,
        Password = foobar123,
        PrimaryEmail = timmy@example.biz,
        GivenName = Timmy,
        SurName = Smith
);


/* ready to create account and user from information collected in new account form or previously collected  or create an account and user in one call*/
/* all information needed to create both an account and a user should be collected before beginning this process */


userresource = dcoord.AccountUserCreate(user);

while(userresource.status != 201){
        /* error handling. potentially reprompt user for corrections
        /* Error codes:
        AccountUsernameRegistered                       Username already Registered                     400
        AccountActiveUserCountReachedMaxLimit           Active User Count has reached the maximum limit 401
        AccountUserPrivilegeInsufficient                Requestor Privilege Insufficient                403
        AccountUserCannotPromoteUserToHigherPrivilege   Creating User may only promote user to the      403
                                                        same privilege as the creating user    
        AccountUserAccountIdNotFound                    Account Id not found                            404
        AccountStatusInvalid                            Account Status Invalid                          400
        */

        userresource = dcoord.AccountUserCreate(user)
}

/* user created */

/* fetch DST */
shortdst = dcoord.securitytokenservice(usercredentials)

Template for AccountUserCreate

HTTP/1.1 201 Created
Date: Tue, 18 Feb 2014 20:08:56 GMT
Server: Apache
Location: https://iot2.p.uvvu.com:7001/rest/1/11/Account/urn:dece:accountid:org:dece:98C61D79D9644410751EAF34C13BADA8/User/urn:dece:userid:org:dece:A8C61D79D9644410751EAF34C13BADA8
x-Transaction-Info: t=1392754137 UwO92ApaMpMAAGlbJOoAAAAP urn:dece:org:org:dece:iot2:emulator:org1:node1 156.154.122.229
Content-Length: 0
Vary: Accept-Encoding
Content-Type: application/xml;charset=UTF-8
Template for AccountUserCreate:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Account xmlns="http://www.decellc.org/schema/2013/10/coordinator" xmlns:ns2="http://www.movielabs.com/md" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" xmlns:ns4="http://www.w3.org/2001/04/xmlenc#">
        <DisplayName>NAME TO DISPLAY</DisplayName>
        <Country>US</Country>
        <UserList>
                <User UserClass="urn:dece:role:user:class:full" xmlns="http://www.decellc.org/schema/2013/10/coordinator" xmlns:ns2="http://www.movielabs.com/md" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" xmlns:ns4="http://www.w3.org/2001/04/xmlenc#">
                        <Name>
                                <GivenName>FIRST NAME</GivenName>
                                <SurName>LAST NAME</SurName>
                        </Name>
                        <ContactInfo>  
                                <PrimaryEmail>
                                        <Value>EMAIL@EMAIL.COM</Value>        
                                        <ConfirmationEndpoint>confirmed</ConfirmationEndpoint>
                                </PrimaryEmail>
                                 <AlternateEmail>    
                                        <Value>ALT-EMAIL@EMAIL.COM</Value>      
                                        <ConfirmationEndpoint>confirmed</ConfirmationEndpoint>  
                                </AlternateEmail>
                        </ContactInfo>
                        <Languages>
                                <Language>EN-US</Language>
                        </Languages>
                        <Credentials>
                                <Username>marykowalski</Username>    
                                <Password>gre-BnU-127-zY3</Password>
                        </Credentials>
                </User>
        </UserList>
</Account>

Example ResourcePropertyQuery request to check for an existing user associated with the provided email address:

POST https://iot2.p.uvvu.com:7001/rest/1/11/Info HTTP/1.1
Content-Type: application/xml
Content-Length: 37
Host: iot2.p.uvvu.com:7001
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
 
//User[Credentials[Username='Craig']]
 
HTTP/1.1 404 Not Found
Date: Wed, 23 Jul 2014 21:22:25 GMT
Server: Apache
Set-Cookie: JSESSIONID=10gi36bxo29l31ge98j2n1o7f.api1;Path=/rest/1/11;Secure
Expires: Thu, 01 Jan 1970 00:00:00 GMT
x-Transaction-Info: t=1406150546 U9AnkQofmIgAAD13RP4AAAA7 urn:dece:org:org:dece:RET 10.31.153.241
Vary: Accept-Encoding
Content-Length: 615
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Content-Type: application/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorList xmlns="http://www.decellc.org/schema/2013/10/coordinator" xmlns:ns2="http://www.movielabs.com/schema/md/v2.1/md" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" xmlns:ns4="http://www.w3.org/2001/04/xmlenc#">
    <Error ErrorID="urn:dece:errorid:org:dece:NotFound">
        <Reason Language="en">The requested resource was not found.</Reason>
        <OriginalRequest>https://iot2.p.uvvu.com/rest/1/11/Info</OriginalRequest>
        <ErrorLink>https://iot2.q.uvvu.com:7001/rest/1/11/error/en/ErrorList.html#NotFound</ErrorLink>
    </Error>
</ErrorList>

Example ResourcePropertyQuery request to ensure the username is available
POST https://iot2.p.uvvu.com:7001/rest/1/11/Info HTTP/1.1
Content-Type: application/xml
Content-Length: 53
Host: iot2.p.uvvu.com:7001
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
 
//User[Credentials/Username[matches(.,'.........')]]
 
HTTP/1.1 404 Not Found

Date: Wed, 23 Jul 2014 21:24:23 GMT
Server: Apache
Set-Cookie: JSESSIONID=1apyhtv5x65yc15xsq4432xdng.api3;Path=/rest/1/11;Secure
Expires: Thu, 01 Jan 1970 00:00:00 GMT
x-Transaction-Info: t=1406150677 U9AoBwofmIgAADouKcQAAAAT urn:dece:org:org:dece:RET 10.31.153.241
Vary: Accept-Encoding
Content-Length: 615
Keep-Alive: timeout=15, max=100
Connection: Keep-Alive
Content-Type: application/xml;charset=UTF-8
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorList xmlns="http://www.decellc.org/schema/2013/10/coordinator" xmlns:ns2="http://www.movielabs.com/schema/md/v2.1/md" xmlns:ns3="http://www.w3.org/2000/09/xmldsig#" xmlns:ns4="http://www.w3.org/2001/04/xmlenc#">
    <Error ErrorID="urn:dece:errorid:org:dece:NotFound">
        <Reason Language="en">The requested resource was not found.</Reason>
        <OriginalRequest>https://iot.p.uvvu.com/rest/1/11/Info</OriginalRequest>
        <ErrorLink>https://iot.q.uvvu.com/rest/1/11/error/en/ErrorList.html#NotFound</ErrorLink>
    </Error>
</ErrorList>