Merge branch 'job-token-docs' into 'master'

Add specs for job token and add doc examples

See merge request gitlab-org/gitlab!72324

doc/api/jobs.md

@@ -400,11 +400,12 @@ Retrieve the job that generated a job token.
 GET /job
 ```
 
-Examples
+Examples (must run as part of the [`script`](../ci/yaml/index.md#script) section of a [CI/CD job](../ci/jobs/index.md)):
 
 ```shell
-curl --header "JOB-TOKEN: <your_job_token>" "https://gitlab.example.com/api/v4/job"
-curl "https://gitlab.example.com/api/v4/job?job_token=<your_job_token>"
+curl --header "Authorization: Bearer $CI_JOB_TOKEN" "${CI_API_V4_URL}/job"
+curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "${CI_API_V4_URL}/job"
+curl "${CI_API_V4_URL}/job?job_token=$CI_JOB_TOKEN"
 ```
 
 Example of response

spec/lib/gitlab/auth/auth_finders_spec.rb

@@ -873,8 +873,11 @@ RSpec.describe Gitlab::Auth::AuthFinders do
   end
 
   describe '#find_user_from_job_token' do
+    let(:token) { job.token }
+
     subject { find_user_from_job_token }
 
+    shared_examples 'finds user when job token allowed' do
       context 'when the token is in the headers' do
         before do
           set_header(described_class::JOB_TOKEN_HEADER, token)
@@ -898,20 +901,37 @@ RSpec.describe Gitlab::Auth::AuthFinders do
 
         it_behaves_like 'find user from job token'
       end
+    end
+
+    context 'when route setting allows job_token' do
+      let(:route_authentication_setting) { { job_token_allowed: true } }
 
-    context 'when the job token is provided via basic auth' do
+      include_examples 'finds user when job token allowed'
+    end
+
+    context 'when route setting is basic auth' do
       let(:route_authentication_setting) { { job_token_allowed: :basic_auth } }
+
+      context 'when the token is provided via basic auth' do
         let(:username) { ::Gitlab::Auth::CI_JOB_USER }
-      let(:token) { job.token }
 
         before do
           set_basic_auth_header(username, token)
         end
 
         it { is_expected.to eq(user) }
+      end
+
+      include_examples 'finds user when job token allowed'
+    end
+
+    context 'when route setting job_token_allowed is invalid' do
+      let(:route_authentication_setting) { { job_token_allowed: false } }
 
-      context 'credentials are provided but route setting is incorrect' do
-        let(:route_authentication_setting) { { job_token_allowed: :unknown } }
+      context 'when the token is provided' do
+        before do
+          set_header(described_class::JOB_TOKEN_HEADER, token)
+        end
 
         it { is_expected.to be_nil }
       end