Editing CLOT Authentication


This page describes how [[CLOT]] creators can authenticate players on their website.  This means that when a player comes to your CLOT website, you can find out who they are on warzone.com.  

If you want to allow players to perform actions on the ladder (adding themselves, removing themselves, forming teams, etc.), using this authentication system is recommended.  However, it's possible to create a CLOT without authentication if you perform these kinds of actions yourself, or trust players to do it correctly.


== Implementing Authentication ==

=== Step 1: Create a log-in page ===

Create a page on your CLOT website to receive player credentials.  For our example, we'll assume this page is located at http://example.com/login

This page will be passed two querystring parameters - '''token''' and '''clotpass'''.   Here's the procedure you should take when implementing this page:

# Verify that both querystring parameters are present ('''token''' and '''clotpass''').
# Verify that the '''token''' in the querystring contains only numerical digits.
# Call Warzone's [[Validate invite token API]] with the '''token''' from the querystring.
# Verify that the Validate Token API returns a '''clotpass''' field.
# Verify the '''clotpass''' in the querystring exactly matches the '''clotpass''' returned from the Validate Token API.
# Store the '''token''' in the user's current session.
# Redirect the user to another page on your site.

If any of the verification steps fail, you should redirect the user to another page on your site and display an error message there.  

Once the token is written into the user's current session, you may check for this on any page from your website, and if it's present, you know the user is authenticated.  This token is the user's invite token, suitable for passing to the [[Create game API]].  You don't need to call the Validate Token API again as long as the user's session stays intact.  You may wish to provide a Sign Out button that clears the token from the user's current session.

It's important to redirect, both on success and failure, so that the clotpass isn't ever displayed in the user's address bar.  You don't want them to copy a URL with it and share it publicly without realizing it contains information they want to keep to themselves.  Redirecting ensures they don't accidentally share it.

=== Step 2: Register your log-in page with Warzone ===

# Visit the following page in your browser: https://www.warzone.com/CLOT/Config
# Type in the URL to your log-in page into the text box under CLOT Redirect Url (http://example.com/login in this example)
# Click Save

=== Step 3: Link to Warzone's authentication page from your website ===

# Visit, once again, the following page in your browser: https://www.warzone.com/CLOT/Config
# Copy your CLOT Authentication URL from this page
# Provide a "Sign In" link on your website that points at your CLOT Authentication URL.

Players who click your Sign In link will be redirected back to your login page with their token and clotpass added.  This CLOT Authentication URL is also suitable for sharing on the Warzone forums or anywhere else you'd like to attract players.

== Optional: State parameter ==

You may optionally append a '''state''' querystring argument to your CLOT Authentication URL.  This will be passed through unchanged to your log-in page.

For example, say you wanted to run two ladders from the same site, a 1v1 ladder and a 2v2 ladder.  You may wish to provide a link that directly joins a player to your 1v1 ladder.  However, your log-in page wouldn't know which ladder to join the player to.

To fix this, append &state=1v1 to the end of your CLOT Authentication URL.  For example, https://www.warzone.com/CLOT/Auth?p=1234567&state=1v1.   Once the player is redirected, your log-in page will be called with this state, for example: http://example.com/login?token=12345&clotpass=asdfg&state=1v1.  Your code can look for this '''state''' parameter and parse its meaning.

[[Category:CLOT]]