This is an example of how to use AuthKit with an HTML frontend.
``` Clicking the "Sign in" and "Sign out" links should invoke actions on our server, which we'll set up next. ### Add a sign-in endpoint We'll need a sign-in endpoint to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. This endpoint should generate an AuthKit authorization URL server side and redirect the user to it. You can use the optional state parameter to encode arbitrary information to help restore application `state` between redirects. For this guide we'll be using the `sinatra` web server for Ruby. This guide won't cover how to set up a Sinatra app, but you can find more information in the [Sinatra documentation](https://sinatrarb.com/intro.html). #### server.rb ```rb require "dotenv/load" require "workos" require "sinatra" WorkOS.configure do |config| config.key = ENV["WORKOS_API_KEY"] end set :port, 3000 get "/" do send_file "index.html" end get "/login" do authorization_url = WorkOS::UserManagement.authorization_url( provider: "authkit", client_id: ENV["WORKOS_CLIENT_ID"], redirect_uri: "http://localhost:3000/callback" ) redirect authorization_url end ``` > WorkOS will redirect to your [Redirect URI](https://workos.com/docs/glossary/redirect-uri) if there is an issue generating an authorization URL. Read our [API Reference](https://workos.com/docs/reference) for more details. ### Add a callback endpoint Next, let's add the callback endpoint (referenced in [Configure a redirect URI](https://workos.com/docs/authkit/1-configure-your-project/configure-a-redirect-uri)) which will exchange the authorization code (valid for 10 minutes) for an authenticated User object. #### server.rb ```rb get "/callback" do code = params["code"] begin auth_response = WorkOS::UserManagement.authenticate_with_code( client_id: ENV["WORKOS_CLIENT_ID"], code: code ) # Use the information in auth_response for further business logic. redirect "/" rescue => e puts e redirect "/login" end end ``` ## (3) Handle the user session Session management helper methods are included in our SDKs to make integration easy. For security reasons, sessions are automatically "sealed", meaning they are encrypted with a strong password. ### Create a session password The SDK requires you to set a strong password to encrypt cookies. This password must be 32 characters long. You can generate a secure password by using the [1Password generator](https://1password.com/password-generator/) or the `openssl` library via the command line: ```bash title="Generate a strong password" openssl rand -base64 32 ``` Then add it to the environment variables file. ```plain title=".env" WORKOS_API_KEY='sk_example_123456789' WORKOS_CLIENT_ID='client_123456789' # +diff-start WORKOS_COOKIE_PASSWORD='Welcome, #{user[:email]}!
) : "" html = File.read("index.html") html.gsub("{{USER_DATA}}", user_info) end ``` And, we should make sure to update the index page to present this info. #### index.html ```htmlThis is an example of how to use AuthKit with an HTML frontend.
``` ### Protected routes Then, use a helper method to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one. #### server.rb ```rb helpers do def with_auth(request, response) session = WorkOS::UserManagement.load_sealed_session( client_id: ENV["WORKOS_CLIENT_ID"], session_data: request.cookies["wos_session"], cookie_password: ENV["WORKOS_COOKIE_PASSWORD"] ) session.authenticate => { authenticated:, reason: } return if authenticated == true redirect "/login" if !authenticated && reason == "NO_SESSION_COOKIE_PROVIDED" # If no session, attempt a refresh begin session.refresh => { authenticated:, sealed_session: } redirect "/login" if !authenticated response.set_cookie( "wos_session", value: sealed_session, httponly: true, secure: true, samesite: "lax" ) # Redirect to the same route to ensure the updated cookie is used redirect request.url rescue => e warn e response.delete_cookie("wos_session") redirect "/login" end end end ``` Call the helper method in the route that should only be accessible to logged in users. #### server.rb ```rb get "/dashboard" do with_auth(request, response) session = WorkOS::UserManagement.load_sealed_session( client_id: ENV["WORKOS_CLIENT_ID"], session_data: request.cookies["wos_session"], cookie_password: ENV["WORKOS_COOKIE_PASSWORD"] ) session.authenticate => { authenticated:, user: } redirect "/login" if !authenticated puts "User #{user[:first_name]} is logged in" # Render a dashboard view end ``` ### Ending the session Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app's [Sign-out redirect](https://workos.com/docs/authkit/sessions/configuring-sessions/sign-out-redirect) location, which is configured in the WorkOS dashboard. #### server.rb ```rb require 'rack/csrf' require 'json' use Rack::Session::Cookie, secret: 'replace-me-with-a-real-secret' use Rack::Csrf, raise: true, field: '_csrf' helpers do def csrf_token Rack::Csrf.token(env) end def csrf_tag "" end end # Endpoint to get CSRF token for forms get "/csrf-token" do content_type :json { csrfToken: csrf_token }.to_json end post "/logout" do session = WorkOS::UserManagement.load_sealed_session( client_id: ENV["WORKOS_CLIENT_ID"], session_data: request.cookies["wos_session"], cookie_password: ENV["WORKOS_COOKIE_PASSWORD"] ) url = session.get_logout_url response.delete_cookie("wos_session") # After log out has succeeded, the user will be redirected to your # app homepage which is configured in the WorkOS dashboard redirect url end ``` > **Note:** CSRF Protection: The logout endpoint uses POST to prevent > unintended logouts from browser prefetching. CSRF protection with >Rack::Csrf prevents cross-site request forgery attacks. The
> csrf\_tag helper method generates a hidden form field with the
> CSRF token.
> If you haven't configured a [Sign-out redirect](https://workos.com/docs/authkit/sessions/configuring-sessions/sign-out-redirect) in the WorkOS dashboard, users will see an error when logging out.
## Validate the authentication flow
To test all of this out, start your server with `ruby server.rb`, navigate to `localhost:3000`, and sign up for an account.
You can then sign in with the newly created credentials and see the user listed in the **Users** section of the [WorkOS Dashboard](https://dashboard.workos.com).
