authentication.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Authentication  Reference</title>
    <link rel="stylesheet" type="text/css" href="css/jazzy.css" />
    <link rel="stylesheet" type="text/css" href="css/highlight.css" />
    <meta charset='utf-8'>
    <script src="js/jquery.min.js" defer></script>
    <script src="js/jazzy.js" defer></script>
    
  </head>
  <body>
    <a title="Authentication  Reference"></a>
    <header>
      <div class="content-wrapper">
        <p><a href="index.html">Moya Docs</a> (82% documented)</p>
      </div>
    </header>
    <div class="content-wrapper">
      <p id="breadcrumbs">
        <a href="index.html">Moya Reference</a>
        <img id="carat" src="img/carat.png" />
        Authentication  Reference
      </p>
    </div>
    <div class="content-wrapper">
      <nav class="sidebar">
        <ul class="nav-groups">
          <li class="nav-group-name">
            <a href="Guides.html">Guides</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="authentication.html">Authentication</a>
              </li>
              <li class="nav-group-task">
                <a href="communityprojects.html">CommunityProjects</a>
              </li>
              <li class="nav-group-task">
                <a href="endpoints.html">Endpoints</a>
              </li>
              <li class="nav-group-task">
                <a href="plugins.html">Plugins</a>
              </li>
              <li class="nav-group-task">
                <a href="providers.html">Providers</a>
              </li>
              <li class="nav-group-task">
                <a href="readme.html">README</a>
              </li>
              <li class="nav-group-task">
                <a href="reactiveswift.html">ReactiveSwift</a>
              </li>
              <li class="nav-group-task">
                <a href="releasing.html">Releasing</a>
              </li>
              <li class="nav-group-task">
                <a href="rxswift.html">RxSwift</a>
              </li>
              <li class="nav-group-task">
                <a href="targets.html">Targets</a>
              </li>
              <li class="nav-group-task">
                <a href="testing.html">Testing</a>
              </li>
              <li class="nav-group-task">
                <a href="threading.html">Threading</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Classes.html">Classes</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Classes/CancellableToken.html">CancellableToken</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/CredentialsPlugin.html">CredentialsPlugin</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/Endpoint.html">Endpoint</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/MoyaProvider.html">MoyaProvider</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NetworkActivityPlugin.html">NetworkActivityPlugin</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NetworkLoggerPlugin.html">NetworkLoggerPlugin</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/NetworkLoggerPlugin/Configuration.html">– Configuration</a>
              </li>
              <li class="nav-group-task">
                <a href="Classes/Response.html">Response</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Enums.html">Enumerations</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Enums/AuthorizationType.html">AuthorizationType</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/EndpointSampleResponse.html">EndpointSampleResponse</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/MoyaError.html">MoyaError</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/MultiTarget.html">MultiTarget</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/NetworkActivityChangeType.html">NetworkActivityChangeType</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/StubBehavior.html">StubBehavior</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/Task.html">Task</a>
              </li>
              <li class="nav-group-task">
                <a href="Enums/ValidationType.html">ValidationType</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Extensions.html">Extensions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Extensions/Method.html">Method</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/Request.html">Request</a>
              </li>
              <li class="nav-group-task">
                <a href="Extensions/URL.html">URL</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Functions.html">Functions</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Functions.html#/s:4Moya23convertResponseToResult_7request4data5errors0E0OyAA0C0CAA0A5ErrorOGSo17NSHTTPURLResponseCSg_10Foundation10URLRequestVSgAP4DataVSgs0I0_pSgtF">convertResponseToResult(_:request:data:error:)</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Protocols.html">Protocols</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Protocols/AccessTokenAuthorizable.html">AccessTokenAuthorizable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/Cancellable.html">Cancellable</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/MoyaProviderType.html">MoyaProviderType</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/PluginType.html">PluginType</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/RequestType.html">RequestType</a>
              </li>
              <li class="nav-group-task">
                <a href="Protocols/TargetType.html">TargetType</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Structs.html">Structures</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/MultipartFormData.html">MultipartFormData</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/MultipartFormData/FormDataProvider.html">– FormDataProvider</a>
              </li>
              <li class="nav-group-task">
                <a href="Structs/ProgressResponse.html">ProgressResponse</a>
              </li>
            </ul>
          </li>
          <li class="nav-group-name">
            <a href="Typealiases.html">Type Aliases</a>
            <ul class="nav-group-tasks">
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya10Completiona">Completion</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya19DownloadDestinationa">DownloadDestination</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya5Imagea">Image</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/ImageType">ImageType</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya9ImageTypea">ImageType</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya12JSONEncodinga">JSONEncoding</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya6Methoda">Method</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya17ParameterEncodinga">ParameterEncoding</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya13ProgressBlocka">ProgressBlock</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya18RequestInterceptora">RequestInterceptor</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya24RequestMultipartFormDataa">RequestMultipartFormData</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya7Sessiona">Session</a>
              </li>
              <li class="nav-group-task">
                <a href="Typealiases.html#/s:4Moya11URLEncodinga">URLEncoding</a>
              </li>
            </ul>
          </li>
        </ul>
      </nav>
      <article class="main-content">
        <section>
          <section class="section">
            
            <h1 id='authentication' class='heading'>Authentication</h1>

<p>Authentication can be tricky. There are a few ways network requests
can be authenticated. Let&rsquo;s discuss two of the common ones.</p>
<h2 id='basic-http-auth' class='heading'>Basic HTTP Auth</h2>

<p>HTTP auth is a username/password challenge built into the HTTP protocol
itself. If you need to use HTTP auth, you can provide a <code><a href="Classes/CredentialsPlugin.html">CredentialsPlugin</a></code>
when initializing your provider.</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">provider</span> <span class="o">=</span> <span class="kt">MoyaProvider</span><span class="o">&lt;</span><span class="kt">YourAPI</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">plugins</span><span class="p">:</span> <span class="p">[</span><span class="kt">CredentialsPlugin</span> <span class="p">{</span> <span class="n">_</span> <span class="o">-&gt;</span> <span class="kt">URLCredential</span><span class="p">?</span> <span class="k">in</span>
        <span class="k">return</span> <span class="kt">URLCredential</span><span class="p">(</span><span class="nv">user</span><span class="p">:</span> <span class="s">"user"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"passwd"</span><span class="p">,</span> <span class="nv">persistence</span><span class="p">:</span> <span class="o">.</span><span class="k">none</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">])</span>
</code></pre>

<p>This specific examples shows a use of HTTP that authenticates <em>every</em> request,
which is usually not necessary. This might be a better idea:</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">provider</span> <span class="o">=</span> <span class="kt">MoyaProvider</span><span class="o">&lt;</span><span class="kt">YourAPI</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">plugins</span><span class="p">:</span> <span class="p">[</span><span class="kt">CredentialsPlugin</span> <span class="p">{</span> <span class="n">target</span> <span class="o">-&gt;</span> <span class="kt">URLCredential</span><span class="p">?</span> <span class="k">in</span>
        <span class="k">switch</span> <span class="n">target</span> <span class="p">{</span>
        <span class="k">case</span> <span class="o">.</span><span class="nv">targetThatNeedsAuthentication</span><span class="p">:</span>
            <span class="k">return</span> <span class="kt">URLCredential</span><span class="p">(</span><span class="nv">user</span><span class="p">:</span> <span class="s">"user"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"passwd"</span><span class="p">,</span> <span class="nv">persistence</span><span class="p">:</span> <span class="o">.</span><span class="k">none</span><span class="p">)</span>
        <span class="k">default</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">nil</span>
        <span class="p">}</span>
    <span class="p">}</span>
<span class="p">])</span>
</code></pre>
<h2 id='access-token-auth' class='heading'>Access Token Auth</h2>

<p>Another common method of authentication is by using an access token.
Moya provides an <code><a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a></code> that supports both <code>Bearer</code> authentication
using a <a href="https://jwt.io/introduction/">JWT</a> and <code>Basic</code> authentication for API keys.
Also there is support for custom authorization types.</p>

<p>There are two steps required to start using an <code><a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a></code>.</p>

<ol>
<li><p>You need to add an <code><a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a></code> to your <code><a href="Classes/MoyaProvider.html">MoyaProvider</a></code> like this:</p>
<pre class="highlight plaintext"><code>let token = "eyeAm.AJsoN.weBTOKen"
let authPlugin = AccessTokenPlugin { _ in token }
let provider = MoyaProvider&lt;YourAPI&gt;(plugins: [authPlugin])
</code></pre>

<p>The <code><a href="Structs/AccessTokenPlugin.html">AccessTokenPlugin</a></code> initializer accepts a <code>tokenClosure</code> that is responsible
for returning the token to be applied to the header of the request.</p></li>
<li><p>Your <code><a href="Protocols/TargetType.html">TargetType</a></code> needs to conform to the <code><a href="Protocols/AccessTokenAuthorizable.html">AccessTokenAuthorizable</a></code> protocol:</p></li>
</ol>
<pre class="highlight plaintext"><code>extension YourAPI: TargetType, AccessTokenAuthorizable {
    case targetThatNeedsBearerAuth
    case targetThatNeedsBasicAuth
    case targetThatNeedsCustomAuth
    case targetDoesNotNeedAuth

    var authorizationType: AuthorizationType? {
        switch self {
            case .targetThatNeedsBearerAuth:
                return .bearer
            case .targetThatNeedsBasicAuth:
                return .basic
            case .targetThatNeedsCustomAuth:
                return .custom("CustomAuthorizationType")
            case .targetDoesNotNeedAuth:
                return nil
            }
        }
}
</code></pre>

<p>The <code><a href="Protocols/AccessTokenAuthorizable.html">AccessTokenAuthorizable</a></code> protocol requires you to implement a single
property, <code>authorizationType</code>, which is an enum representing the header to 
use for the request.</p>

<p><strong>Bearer HTTP Auth</strong>
Bearer requests are authorized by adding a HTTP header of the following form:</p>
<pre class="highlight plaintext"><code>Authorization: Bearer &lt;token&gt;
</code></pre>

<p><strong>Basic API Key Auth</strong>
Basic requests are authorized by adding a HTTP header of the following form:</p>
<pre class="highlight plaintext"><code>Authorization: Basic &lt;token&gt;
</code></pre>

<p><strong>Custom API Key Auth</strong>
Custom requests are authorized by adding a HTTP header of the following form:</p>
<pre class="highlight plaintext"><code>Authorization: &lt;Custom&gt; &lt;token&gt;
</code></pre>
<h2 id='oauth' class='heading'>OAuth</h2>

<p>OAuth is quite a bit trickier. It involves a multi step process that is often
different between different APIs. You <em>really</em> don&rsquo;t want to do OAuth yourself –
there are other libraries to do it for you. <a href="https://github.com/rheinfabrik/Heimdallr.swift">Heimdallr.swift</a>,
for example. The trick is just getting Moya and whatever you&rsquo;re using to talk
to one another.</p>

<p>Moya is built with OAuth in mind. <q>Signing</q> a network request with OAuth can
itself sometimes require network requests be performed <em>first</em>, so signing
a request for Moya is an asynchronous process. Let&rsquo;s see an example.</p>
<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">requestClosure</span> <span class="o">=</span> <span class="p">{</span> <span class="p">(</span><span class="nv">endpoint</span><span class="p">:</span> <span class="kt">Endpoint</span><span class="p">,</span> <span class="nv">done</span><span class="p">:</span> <span class="kt">URLRequest</span> <span class="o">-&gt;</span> <span class="kt">Void</span><span class="p">)</span> <span class="k">in</span>
    <span class="k">let</span> <span class="nv">request</span> <span class="o">=</span> <span class="k">try!</span> <span class="n">endpoint</span><span class="o">.</span><span class="nf">urlRequest</span><span class="p">()</span> <span class="c1">// This is the request Moya generates</span>

    <span class="kt">YourAwesomeOAuthProvider</span><span class="o">.</span><span class="nf">signRequest</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="nv">completion</span><span class="p">:</span> <span class="p">{</span> <span class="n">signedRequest</span> <span class="k">in</span>
        <span class="c1">// The OAuth provider can make its own network calls to sign your request.</span>
        <span class="c1">// However, you *must* call `done()` with the signed so that Moya can</span>
        <span class="c1">// actually send it!</span>
        <span class="nf">done</span><span class="p">(</span><span class="o">.</span><span class="nf">success</span><span class="p">(</span><span class="n">signedRequest</span><span class="p">))</span>
    <span class="p">})</span>
<span class="p">}</span>
<span class="k">let</span> <span class="nv">provider</span> <span class="o">=</span> <span class="kt">MoyaProvider</span><span class="o">&lt;</span><span class="kt">YourAPI</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">requestClosure</span><span class="p">:</span> <span class="n">requestClosure</span><span class="p">)</span>
</code></pre>

<p>(Note that Swift is able to infer the <code>YourAPI</code> generic – neat!)</p>
<h2 id='handle-session-refresh-in-your-provider-subclass' class='heading'>Handle session refresh in your Provider subclass</h2>

<p>You can take a look at example of session refreshing before each request in <a href="Examples/SubclassingProvider.md">Examples/SubclassingProvider</a>.
It is based on <a href="https://github.com/artsy/eidolon/blob/master/Kiosk/App/Networking/Networking.swift">Artsy&rsquo;s networking implementation</a>.</p>

          </section>
        </section>
        <section id="footer">
          <p>&copy; 2020 <a class="link" href="https://github.com/Moya/Moya" target="_blank" rel="external">Ash Furrow</a>. All rights reserved. (Last updated: 2020-02-24)</p>
          <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.9.6</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external">Realm</a> project.</p>
        </section>
      </article>
    </div>
  </body>
</div>
</html>