Package: rownd-django
Rownd bindings for DjangoEasily add Rownd instant accounts to your Django-backed apps.InstallationBegin by adding therownd_djangopackage to your dependencies. Inrequirements.txt, this would look like:rownd_django>=1.0.0NOTE: This plugin only works with Django v3 and above. We strongly recommend upgrading if you're
using something older. If you can't for some reason, pleaseget in touch.Next, add the Rownd app and authentication backend to your Djangosettings.pyfile.INSTALLED_APPS=[...'rownd_django',]AUTHENTICATION_BACKENDS=['rownd_django.auth.backend.RowndAuthenticationBackend','django.contrib.auth.backends.ModelBackend']If you're using Django REST Framework, then add the Rownd authentication class to yourREST_FRAMEWORKsettings.REST_FRAMEWORK={'DEFAULT_AUTHENTICATION_CLASSES':['rownd_django.auth.backend.RowndApiAuthentication',]}Finally, add your Rownd app credentials to your Djangosettings.pyfile. You can obtain these from theRownd dashboard.
These credentials enable the Rownd authentication backend to communicate with the Rownd API.ROWND={'APP_KEY':'<your app key>','APP_SECRET':'<your app secret>',}A note on Google Sign-inIf you plan to use Google sign-in, you'll need to add or update one last configuration item in yoursettings.pywhile developing locally without HTTPS connections enabled. Without this setting, the
Google One Tap iframe will not load correctly due to a missing Referrer header.SECURE_REFERRER_POLICY = "no-referrer-when-downgrade"Configure the Rownd Hub (required)Rownd authentication requires a small code snippet to be embedded within your app, present on all HTML pages.
Setup for the Hub/snippet itself is outside the scope of this document, but you can find the relevant setup
guides for eithersingle page appsortraditional web apps via vanilla js.Use our SDKs to embed the Hub/snippet in your SPA or use the vanilla JS SDK to add the snippet in your main Django template HTML.Now that everything is set up, you can add Rownd authentication to your APIs or views.UsageThe Rownd Django SDK provides support for both "traditional" Django apps where you have an authentication
session that follows a user across page loads, as well as "single-page" (SPA) Django apps using frameworks
like React, Vue, etc.Single-page apps (SPA) / API-basedWhen using an SPA framework like React, Vue, or similar, you'll likely want to leverage the specific Rownd SDK
for those frameworks. You can find a list of supported frameworks inour documentation.Typically, an SPA will use an API-driven request/response flow which makes typical sessions unnecessary (though Rownd supports them if you
need them). We highly recommend theDjango REST frameworkfor this purpose. Rownd provides plug-and-play
support for the REST framework's authentication API.Here's an example of how you might configure an API to leverage Rownd's authenticator, given the installation instructions above:fromrownd_django.auth.backendimportRowndApiAuthenticationfromrest_framework.permissionsimportIsAuthenticatedfromrest_framework.responseimportResponsefromrest_framework.viewsimportAPIViewclassExampleView(APIView):authentication_classes=[RowndApiAuthentication]permission_classes=[IsAuthenticated]defget(self,request,format=None):content={'user':str(request.user),# `django.contrib.auth.User` instance.'auth':str(request.auth),# None}returnResponse(content)Traditional (non-SPA) apps / session-basedIn this flow, once a user has been authenticated with the Rownd Hub, the Hub will make a request to your
app's backend to set up a session for the user.First, ensure your project has session middleware enabled.MIDDLEWARE=[...'django.contrib.sessions.middleware.SessionMiddleware',...]Next, include the Rowndsession_authenticatorin yoururls.pyfile.urlpatterns=[...path('rownd/',include('rownd_django.auth.urls',namespace='rownd')),...]Finally, update your Rownd Hub code snippet to fire post-authenticate and post-sign-out API requests
to the session authenticator we just enabled.<scripttype="text/javascript">(function(){// Rownd Hub snippet})();</script><scripttype="text/javascript">functiongetCookie(name){letcookieValue=null;if(document.cookie&&document.cookie!==''){constcookies=document.cookie.split(';');for(leti=0;i<cookies.length;i++){constcookie=cookies[i].trim();// Does this cookie string begin with the name we want?if(cookie.substring(0,name.length+1)===(name+'=')){cookieValue=decodeURIComponent(cookie.substring(name.length+1));break;}}}returncookieValue;}_rphConfig.push(['setAppKey','<rownd app key>']);_rphConfig.push(['setPostAuthenticationApi',{method:'post',url:'/rownd/session_authenticate',extra_headers:{'X-CSRFToken':getCookie('csrftoken')}}]);_rphConfig.push(['setPostSignOutApi',{method:'post',url:'/rownd/session_post_sign_out',extra_headers:{'X-CSRFToken':getCookie('csrftoken')}}]);</script>The session authenticator will establish an authenticated session if one doesn't already exist and will return a response
indicating that the Rownd Hub should trigger a page refresh. This is usually necessary for your app views to display
the desired authenticated context. In the event that an authenticated session already exists, the Hub will not trigger
further page refreshes.CSRF ProtectionBy default CSRF protection is disabled on the two sign-in and sign-out routes provided by Rownd. If
you would like to enable it on those endpoints, you must ensure all of your sites views contain thecsrftokencookie and update your settings to enable the CSRF protection. You can find more information
on thecsrftokencookiehere.ROWND={'APP_KEY':'<your app key>','APP_SECRET':'<your app secret>','CSRF_PROTECT_ROUTES':True}Custom User ModelIf you are using a customized user model that changes the defaultUSERNAME_FIELDvalue fromusername,
you must tell the Rownd SDK the property name.ROWND={'USER_MODEL_USERNAME_FIELD':'email',}