feature #913 Add support for SSO errors coming from the API (eiriksm)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

Hello, thanks for this!

I just had a case where a token I used were throwing a runtimeexception because the org in question for the resource, had enforced SAML authentication. This was not something I could explicitly catch and do something with, so here is a PR fixing that.

Thanks again, keep up the good work!

Commits
-------

eec78a7 Add support for SSO errors coming from the API
282fd58 Code style
9a9bec7 phpstan fixes
51b49cb Code style
e566606 Add a test for sso required exception
4588ad5 Code style
54cf8f1 Code style

Author: eiriksm

lib/Github/Exception/SsoRequiredException.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Github\Exception;
+
+/**
+ * SsoRequiredException.
+ */
+class SsoRequiredException extends RuntimeException
+{
+    /** @var string */
+    private $url;
+
+    /**
+     * @param string          $url
+     * @param int             $code
+     * @param \Throwable|null $previous
+     */
+    public function __construct($url, $code = 0, $previous = null)
+    {
+        $this->url = $url;
+
+        parent::__construct('Resource protected by organization SAML enforcement. You must grant your personal token access to this organization.', $code, $previous);
+    }
+
+    /**
+     * @return string
+     */
+    public function getUrl()
+    {
+        return $this->url;
+    }
+}

lib/Github/HttpClient/Plugin/GithubExceptionThrower.php

@@ -5,6 +5,7 @@
 use Github\Exception\ApiLimitExceedException;
 use Github\Exception\ErrorException;
 use Github\Exception\RuntimeException;
+use Github\Exception\SsoRequiredException;
 use Github\Exception\TwoFactorAuthenticationRequiredException;
 use Github\Exception\ValidationFailedException;
 use Github\HttpClient\Message\ResponseMediator;
@@ -103,6 +104,16 @@ public function doHandleRequest(RequestInterface $request, callable $next, calla
                 throw new RuntimeException(implode(', ', $errors), 502);
             }
 
+            if ((403 === $response->getStatusCode()) && $response->hasHeader('X-GitHub-SSO') && 0 === strpos((string) ResponseMediator::getHeader($response, 'X-GitHub-SSO'), 'required;')) {
+                // The header will look something like this:
+                // required; url=https://github.com/orgs/octodocs-test/sso?authorization_request=AZSCKtL4U8yX1H3sCQIVnVgmjmon5fWxks5YrqhJgah0b2tlbl9pZM4EuMz4
+                // So we strip out the first 14 characters, leaving only the URL.
+                // @see https://developer.github.com/v3/auth/#authenticating-for-saml-sso
+                $url = substr((string) ResponseMediator::getHeader($response, 'X-GitHub-SSO'), 14);
+
+                throw new SsoRequiredException($url);
+            }
+
             throw new RuntimeException(isset($content['message']) ? $content['message'] : $content, $response->getStatusCode());
         });
     }

test/Github/Tests/HttpClient/Plugin/GithubExceptionThrowerTest.php

@@ -136,6 +136,16 @@ public static function responseProvider()
                 ),
                 'exception' => new \Github\Exception\RuntimeException('Something went wrong with executing your query', 502),
             ],
+            'Sso required Response' => [
+                'response' => new Response(
+                    403,
+                    [
+                        'Content-Type' => 'application/json',
+                        'X-GitHub-SSO' => 'required; url=https://github.com/orgs/octodocs-test/sso?authorization_request=AZSCKtL4U8yX1H3sCQIVnVgmjmon5fWxks5YrqhJgah0b2tlbl9pZM4EuMz4',
+                    ]
+                ),
+                'exception' => new \Github\Exception\SsoRequiredException('https://github.com/orgs/octodocs-test/sso?authorization_request=AZSCKtL4U8yX1H3sCQIVnVgmjmon5fWxks5YrqhJgah0b2tlbl9pZM4EuMz4'),
+            ],
             'Default handling' => [
                 'response' => new Response(
                     555,