We are incredibly excited to announce that Stormpath is joining forces with Okta. Please visit the Migration FAQs for a detailed look at what this means for Stormpath users.
We're available to answer all questions at support@stormpath.com.
Turnstile is a security framework for Swift inspired by Apache Shiro. It's used to manage the currently executing user account in your application, whether iOS app or backend web application.
Turnstile is the easiest way to add authentication to your Swift apps. Currently, the focus is on a great API for backend Swift apps.
Turnstile is split into three projects:
If you're a developer of an application or product and need to integrate Turnstile, read the docs for Turnstile Core. Otherwise, if you're a developer using a Turnstile integration, read the docs for Turnstile Web.
The easiest way to use Turnstile is with one of its prebuilt integrations with Swift web frameworks. Here are the frameworks and their statuses:
If you'd like to use Turnstile to build your own integration, it's useful to understand key concepts in Turnstile.
The Subject
represents the currently operating user for your application. You'll use this to interact with Turnstile, and safely check if the current user is authenticated properly.
The Subject API in Turnstile also supports registration, however this is a convenience for basic use cases. Since different apps have different rules on registration and user managment, it's expected that you will most likely write your own registration and user management logic.
A realm connects Turnstile to your data store, and allows Turnstile to authenticate and register accounts. Included with Turnstile is a MemoryRealm
, as well as a WebMemoryRealm
which can handle username/password pairs, as well as Facebook and Google login.
The MemoryRealms store information in memory, and will be wiped when the application is restarted.
To write your own Realm, you'll need to implement the Realm
protocol, which is defined as:
public protocol Realm {
func authenticate(credentials: Credentials) throws -> Account
func register(credentials: Credentials) throws -> Account
}
Turnstile provides Credentials
objects for common use cases, like UsernamePassword
, APIKey
, and AccessToken
. Feel free to define a custom type as well.
When Turnstile calls the authenticate
or register
functions, your Realm should check the Credential type and make sure that it's a credential type you support. If not, it should throw UnsupportedCredentialsError()
.
Afterwards, your Realm should check if the credentials are valid. If not, it should throw IncorrectCredentialsError()
.
If the credentials are correct, you should then authenticate the user, and return the account object. The account protocol is simple:
public protocol Account {
var uniqueID: String { get }
}
And voila! You've created your first Realm!
SessionManager is a Turnstile component that manages sessions and persistience for your authentication system. Included with Turnstile is a MemorySessionmanager
, which can persist sessions in memory.
If you're building your own, you'll need to implement the SessionManager
protocol. This is defined as:
public protocol SessionManager {
/// Creates a session for a given Account object and returns the identifier.
func createSession(account: Account) -> String
/// Gets the account ID for the current session identifier.
func restoreAccount(fromSessionID identifier: String) throws -> Account
/// Destroys the session for a session identifier.
func destroySession(identifier: String)
}
When an account is authenticated, and is asks to use the session manager to persist its data, Turnstile calls createSession(account:)
and expects the Session Manager to return a SessionID it can use to restore the account. While you can use whatever you want as a Session ID, we recommend using TurnstileCrypto's Random.secureToken
method to generate a random string with 128 bits of entropy.
When a user comes in with the SessionID, Turnstile calls restoreAccount(fromSessionID:)
and expects the session manager to return the associated account. Note that this can be different from the account in the Realm, since you might not want to make a database call on every request. If the session does not exist, the Session Manager should throw InvalidSessionError()
When the user logs out, destroySession(identifier:)
should delete the session from the session store.
Turnstile Web provides a number of helpers to make authentication for websites easier. TurnstileWeb includes plugins for external login providers, like Facebook, Google, and Digits.
The Facebook and Google Login flows look like the following:
To get started, you first need to register an application with Facebook. After registering your app, go into your app dashboard's settings page. Add the Facebook Login product, and save the changes.
In the Valid OAuth redirect URIs
box, type in a URL you'll use for step 3 in the OAuth process. (eg, http://localhost:8080/login/facebook/consumer
)
To get started, you first need to register an application with Google. Click "Enable and Manage APIs", and then the credentials tab. Create an OAuth Client ID for "Web".
Add a URL you'll use for step 3 in the OAuth process to the Authorized redirect URIs
list. (eg, http://localhost:8080/login/google/consumer
)
TurnstileWeb has Facebook
and Google
objects, which will allow a you to set up your configured application and log users in. To initialize them, use the client ID and secret (sometimes called App ID) from your Facebook or Google developer console:
let facebook = Facebook(clientID: "clientID", clientSecret: "clientSecret")
let google = Google(clientID: "clientID", clientSecret: "clientSecret")
Then, generate a state (you can use Random.secureToken to generate a random string), save it (we recommend setting a cookie on your user's browser), and redirect the user:
// Redirect the user to this URL using your web framework:
facebook.getLoginLink(redirectURL: "http://localhost:8080/login/google/consumer", state: state)
Once the user is redirected back to your application, you can now verify that they've properly authenticated using the state
from the earlier step, and the full URL that the user has been redirected to:
let credentials = try facebook.authenticate(authorizationCodeCallbackURL: url, state: state) as! FacebookAccount
let credentials = try google.authenticate(authorizationCodeCallbackURL: url, state: state) as! GoogleAccount
These can throw the following errors:
InvalidAuthorizationCodeError
if the Authorization Code could not be validatedAPIConnectionError
if we cannot connect to the OAuth serverInvalidAPIResponse
if the server does not respond in a way we expectOAuth2Error
if the OAuth server calls back with an errorIf successful, it will return a FacebookAccount
or GoogleAccount
. These implement the Credentials
protocol, so then can be passed back into your application's Realm for further validation.
The Digits Login flows look like the following:
X-Auth-Service-Provider
the endpoint where the user needs to be authenticated throughX-Verify-Credentials-Authorization
the OAuth tokenGET
request to the URL in the X-Auth-Service-Provider
header with the X-Verify-Credentials-Authorization
header added as the Authorization
header in this request.The easiest way to setup your app with Digits is to use the Fabric app. After you go through the setup you will then be able to access the consumerKey
and consumerSecret
in the Fabric web interface.
let digits = Digits(consumerKey: "consumerKeyGoesHere")
guard
let urlString = request.headers["X-Auth-Service-Provider"],
let url = URL(string: urlString),
let authHeader = request.headers["X-Verify-Credentials-Authorization"],
let oauthParams = OAuthParameters(header: authHeader)
else {
throw Abort.custom(status: .unauthorized, message: "Bad Digits headers")
}
let credentials: Credentials? = OAuthEcho(authServiceProvider: url, oauthParameters: oauthParams)
let account = try digits.authenticate(credentials: credentials!) as! DigitsAccount
For an example of Digits in action using Vapor checkout this app
Turnstile Crypto has tools to help you build authentication in your apps. Specifically, it can help you use BCrypt hashing in your app, as well as generate secure random numbers. Documentation is in the files themselves.
Tests are powered by XCTest. To successfully perform the Facebook Login tests, you must have the following environment variables set:
FACEBOOK_CLIENT_ID
- the Facebook App ID for a test app from the Facebook developer console. FACEBOOK_CLIENT_SECRET
- the Facebook App Secret for a test app from the Facebook developer console. We're always open to contributions! Feel free to join the Stormpath slack channel to discuss how you can contribute!
Turnstile is built by Stormpath, an API service for authentication, authorization, and user management. If you're building a website, API, or app, and need to build authentication and user management, consider using Stormpath for your needs. We're always happy to help!