Skip to main content
MindTouch Success Center

Constructing a Sign-In Link

This article describes how to construct sign-in links to different authentication providers.

Authentication URL Structure

Authentication URL's are tied to an authentication provider id. You can find your authentication provider id's with an HTTP GET request to your site's services API.

https://example.com/@api/deki/site/services?type=auth

Depending upon your site configuration, an API token may be required to access this API. The response is an XML document containing the authentication providers that are configured on the site.

<services count="3" querycount="3" totalcount="3" href="https://example.com/@api/deki/site/services">
    <service id="1" href="https://example.com.com/@api/deki/site/services/1">
        <sid>http://services.mindtouch.com/deki/draft/2006/11/dekiwiki</sid>
        <uri>https://success.mindtouch.com/@api/deki</uri>
        <type>auth</type>
        <description>Local</description>
        <date.modified>2016-10-21T23:32:17Z</date.modified>
        <status>enabled</status>
        <init>native</init>
    </service>
    <service id="2" href="https://example.com/@api/deki/site/services/3">
        <sid>sid://mindtouch/2017/12/sso/saml</sid>
        <uri>https://example.com/@api/deki</uri>
        <type>auth</type>
        <description>Partner SAML SSO Portal</description>
        <date.modified>2018-02-22T20:13:49Z</date.modified>
        <status>enabled</status>
        <init>native</init>
    </service>
    <service id="3" href="https://example.com/@api/deki/site/services/3">
        <sid>sid://mindtouch/2017/12/sso/saml</sid>
        <uri>https://example.com.com/@api/deki</uri>
        <type>auth</type>
        <description>Customer SAML SSO Portal</description>
        <date.modified>2018-02-22T21:14:51Z</date.modified>
        <status>enabled</status>
        <init>native</init>
    </service>
</services>

If you are signed in with a site administrator account, this XML document will be more verbose, containing configurations for each of these authentication providers. Each service element contains an id attribute, representing the authentication provider's id (XPath: /services/service/@id).

The authentication provider id 1 always represents the local authentication provider, the built-in sign-in form located at the Special:UserLogin path. Constructing links directly to Special:UserLogin can lead to problems when handling return URL's.

The {id} can be inserted into the following URL structure to construct an authentication URL

https://example.com/@app/auth/{id}/login

The word default can be used in place of {id}to construct a URL to the default authentication provider.

https://example.com/@app/auth/default/login

An optional returnto URL query parameter contains a URL encoded, fully qualified URL that the user is expected to be navigated to, after authentication. This value is converted into the authentication protocol's native return URL paradigm (ex: RelayState for SAML SSO). This URL must return the same hostname as the authentication endpoint, otherwise the return URL will be dropped.

https://example.com/@app/auth/{id}/login?returnto=https%3A%2F%2Fexample.com%2Ffoo%2Fbar%3Fbaz%3Dqux
https://example.com/@app/auth/default/login?returnto=https%3A%2F%2Fexample.com%2Ffoo%2Fbar%3Fbaz%3Dqux

The Special:UserLogin built-in sign-in form uses special URL query parameters construct a post-authentication HTTP redirect. These query parameters, returntotitle and returnquery, are generated and handled by the MindTouch platform with unique, special character encoding. It is not recommended that you try to construct a URL to Special:UserLogin with query parameters. Instead, use the method described above, using authentication provider id 1.

// Constructing an authentication URL with a return URL to https://example.com/foo/bar?baz=qux

// Don't try this...
https://example.com/Special:UserLogin?returntotitle=foo%2Fbar&returnquery=baz%3Dqux

// Instead, construct this
https://example.com/@app/auth/1/login?returnto=https%3A%2F%2Fexample.com%2Ffoo%2Fbar%3Fbaz%3Dqux

Building the Markup

Putting everything together, using DekiScript, a sign-in link with a return to the current page, can be achieved with this code.

<a href=(site.homepage.uri .. '@app/auth/{id}/login?returnto=' .. uri.encode(page.uri))>"Sign in"</a>

 

  • Was this article helpful?