Merge pull request #11 from MicrosoftDocs/main

Latest wiki migration changes

.github/workflows/linkchecker.yml

@@ -0,0 +1,31 @@
+name: Validate existing links
+
+on:
+  push:
+  repository_dispatch:
+  workflow_dispatch:
+  schedule:
+    - cron: "00 18 * * *"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/[email protected]
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+        with:
+          args: --verbose --exclude-file .lycheeignore --no-progress './**/*.md' --exclude-mail
+          fail: true
+
+      - name: Create Issue From File
+        if: always() && env.lychee_exit_code != 0 && github.event_name != 'pull_request'
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue

.lycheeignore

@@ -0,0 +1,5 @@
+https://aka.ms/msal/estsr/guidance
+xref:.+
+https://mvnrepository.com/artifact/com.microsoft.azure/msal4j/1.14.0-beta
+https://mvnrepository.com/artifact/com.microsoft.azure/javamsalruntime
+https://mvnrepository.com/artifact/com.microsoft.azure/msal4j-brokers

.openpublishing.publish.config.json

@@ -34,15 +34,6 @@
       },
       "SplitTOC": [
         "java/docs-ref-autogen/toc.yml"
-      ],
-      "JoinTOCPlugin": [
-        {
-          "TopLevelTOC": "java/docs-ref-mapping/reference.yml",
-          "ReferenceTOC": "java/docs-ref-autogen/toc.yml",
-          "ReferenceTOCUrl": "/java/api/msal-java/toc.json",
-          "ConceptualTOC": "java/docs-ref-conceptual/toc.yml",
-          "ConceptualTOCUrl": "/java/msal-java/toc.json"
-        }
       ]
     },
     {
@@ -74,6 +65,15 @@
   ],
   "branch_target_mapping": {},
   "docs_build_engine": {},
+  "JoinTOCPlugin": [
+    {
+      "TopLevelTOC": "java/docs-ref-mapping/reference.yml",
+      "ReferenceTOC": "java/docs-ref-autogen/toc.yml",
+      "ReferenceTOCUrl": "/java/api/msal-java/toc.json",
+      "ConceptualTOC": "msal-java-articles/toc.yml",
+      "ConceptualTOCUrl": "/entra/msal/java/toc.json"
+    }
+  ],
   "skip_source_output_uploading": false,
   "contribution_branch_mappings": {},
   "dependent_packages": [
@@ -92,5 +92,5 @@
       "version": "latest"
     }
   ],
-  "need_generate_pdf_url_template": false
+  "need_generate_pdf_url_template": true
 }

README.md

@@ -1,3 +1,23 @@
+# Microsoft Authentication Library (MSAL) for Java Documentation
+
+This is the documentation repository for Microsoft Authentication Library (MSAL) for .NET. If you are looking for the library, refer to [AzureAD/microsoft-authentication-library-for-java](https://github.com/AzureAD/microsoft-authentication-library-for-java).
+
+## Contributions
+
+Contributions to our documentation are welcome. Make sure to familiarize yourself with the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/) and the [Contributor Guide](https://learn.microsoft.com/contribute/) before making any changes.
+
+> **Warning**
+> **Do not** modify any YML files in the `java/docs-ref-autogen` folder - those are generated automatically from the library source code and any changes will be automatically overwritten the next time the documentation Continuous Integration (CI) job runs. To make changes to any API docs you will need to open a pull request in the [AzureAD/microsoft-authentication-library-for-java](https://github.com/AzureAD/microsoft-authentication-library-for-java) repository.
+
+If you would like to author an entirely new document (e.g., for a new scenario), make sure to [open an issue](https://github.com/MicrosoftDocs/microsoft-authentication-library-java/issues) first. This will allow the engineering team to discuss the proposed changes and ensure that it won't be overwritten by future changes.
+
+## API reference documentation automation
+
+Continuous Integration (CI) jobs for this repository are available in the [automation Azure DevOps instance](https://apidrop.visualstudio.com/Content%20CI/_build?definitionScope=%5CPROD%5CGitHub_MicrosoftDocs_microsoft-authentication-library-java).
+
+In this repository, `package.json` on the `main` branch determines what version of `msal4j` the documentation is generated for.
+
 ## Microsoft Open Source Code of Conduct
+
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

java/docfx.json

@@ -28,21 +28,6 @@
           "**/includes/**"
         ]
       },
-      {
-        "files": [
-          "**/*.md"
-        ],
-        "exclude": [
-          "**/obj/**",
-          "**/includes/**",
-          "README.md",
-          "LICENSE",
-          "LICENSE-CODE",
-          "ThirdPartyNotices",
-          "docs-ref-autogen/**",
-          "docs-ref-conceptual/**"
-        ]
-      },
       {
         "files": [
           "**/toc.yml"
@@ -61,7 +46,7 @@
           "**/*.yml"
         ],
         "src": "docs-ref-conceptual",
-        "dest": "msal-java",
+        "dest": "api/overview/msal-java",
         "group": "latest"
       }
     ],
@@ -103,16 +88,28 @@
     "markdownEngineName": "markdig",
     "fileMetadata": {
       "author": {
-        "**.md": "Dickson-Mwendia",
-        "api/**.yml": "Dickson-Mwendia"
+        "docs-ref-autogen/**/**.yml": "Dickson-Mwendia",
+        "docs-ref-conceptual/**/**.md": "Dickson-Mwendia"
       },
       "ms.author": {
-        "**.md": "dmwendia",
-        "api/**.yml": "dmwendia"
+        "docs-ref-autogen/**/**.yml": "dmwendia",
+        "docs-ref-conceptual/**/**.md": "dmwendia"
       },
       "ms.service": {
-        "api/**.yml": "active-directory"
-      }
+        "docs-ref-autogen/**/**.yml": "active-directory",
+        "docs-ref-conceptual/**/**.md": "active-directory"
+      },
+      "titleSuffix": {
+        "docs-ref-autogen/**/**.md": "Microsoft Authentication Library for Java",
+        "docs-ref-conceptual/**/**.yml": "Microsoft Authentication Library for Java"
+      },
+      "ms.topic": {
+        "docs-ref-autogen/**/**.md": "conceptual",
+        "docs-ref-conceptual/**/**.yml": "reference"
+      },
+      "open_to_public_contributors": {
+        "docs-ref-conceptual/**/**.md": true
+      } 
     },
     "template": [],
     "dest": "_site"

java/docs-ref-autogen/com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder.yml

@@ -124,13 +124,17 @@ methods:
   fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder<T>.b2cAuthority(String val)"
   name: "b2cAuthority(String val)"
   nameWithType: "AbstractClientApplicationBase.Builder<T>.b2cAuthority(String val)"
+  summary: "Set URL of the authenticating B2C authority from which MSAL will acquire tokens Valid B2C authorities should look like: https://<something.<wbr>b2clogin.<wbr>com/<tenant>/<policy> MSAL Java also supports a legacy B2C authority format, which looks like: https://<host>/tfp/<tenant>/<policy> However, MSAL Java will eventually stop supporting the legacy format."
   parameters:
-  - name: "val"
+  - description: "a boolean value for validateAuthority"
+    name: "val"
     type: "<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />"
   syntax: "public T b2cAuthority(String val)"
   exceptions:
   - type: "<xref href=\"java.net.MalformedURLException?alt=java.net.MalformedURLException&text=MalformedURLException\" data-throw-if-not-resolved=\"False\" />"
+  desc: "Set URL of the authenticating B2C authority from which MSAL will acquire tokens Valid B2C authorities should look like: https://<something.b2clogin.com/<tenant>/<policy> MSAL Java also supports a legacy B2C authority format, which looks like: https://<host>/tfp/<tenant>/<policy> However, MSAL Java will eventually stop supporting the legacy format. See here for information on how to migrate to the new format: https://aka.ms/msal4j-b2c"
   returns:
+    description: "instance of the Builder on which method was called"
     type: "<xref href=\"T?alt=T&text=T\" data-throw-if-not-resolved=\"False\" />"
 - uid: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder.clientCapabilities(java.util.Set<java.lang.String>)"
   fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder<T>.clientCapabilities(Set<String> capabilities)"
@@ -198,6 +202,18 @@ methods:
   returns:
     description: "instance of the Builder on which method was called"
     type: "<xref href=\"T?alt=T&text=T\" data-throw-if-not-resolved=\"False\" />"
+- uid: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder.instanceDiscovery(boolean)"
+  fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder<T>.instanceDiscovery(boolean val)"
+  name: "instanceDiscovery(boolean val)"
+  nameWithType: "AbstractClientApplicationBase.Builder<T>.instanceDiscovery(boolean val)"
+  summary: "Historically, MSAL would connect to a central endpoint located at \\`\\`https://login.<wbr>microsoftonline.<wbr>com\\`\\` to acquire some metadata, especially when using an unfamiliar authority."
+  parameters:
+  - name: "val"
+    type: "<xref href=\"boolean?alt=boolean&text=boolean\" data-throw-if-not-resolved=\"False\" />"
+  syntax: "public T instanceDiscovery(boolean val)"
+  desc: "Historically, MSAL would connect to a central endpoint located at \\`\\`https://login.microsoftonline.com\\`\\` to acquire some metadata, especially when using an unfamiliar authority. This behavior is known as Instance Discovery. This parameter defaults to true, which enables the Instance Discovery. If you do not know some authorities beforehand, yet still want MSAL to accept any authority that you will provide, you can use a \\`\\`False\\`\\` to unconditionally disable Instance Discovery."
+  returns:
+    type: "<xref href=\"T?alt=T&text=T\" data-throw-if-not-resolved=\"False\" />"
 - uid: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder.logPii(boolean)"
   fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.Builder<T>.logPii(boolean val)"
   name: "logPii(boolean val)"
@@ -287,4 +303,4 @@ typeParameters:
 - name: "T"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AbstractClientApplicationBase.yml

@@ -198,6 +198,13 @@ methods:
   desc: "Computes the URL of the authorization request letting the user sign-in and consent to the application. The URL target the /authorize endpoint of the authority configured in the application object.\n\nOnce the user successfully authenticates, the response should contain an authorization code, which can then be passed in to<xref uid=\"com.microsoft.aad.msal4j.AbstractClientApplicationBase.acquireToken(com.microsoft.aad.msal4j.AuthorizationCodeParameters)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"AbstractClientApplicationBase#acquireToken(AuthorizationCodeParameters)\"></xref> to be exchanged for a token"
   returns:
     type: "<xref href=\"java.net.URL?alt=java.net.URL&text=URL\" data-throw-if-not-resolved=\"False\" />"
+- uid: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.instanceDiscovery()"
+  fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.instanceDiscovery()"
+  name: "instanceDiscovery()"
+  nameWithType: "AbstractClientApplicationBase.instanceDiscovery()"
+  syntax: "public boolean instanceDiscovery()"
+  returns:
+    type: "<xref href=\"boolean?alt=boolean&text=boolean\" data-throw-if-not-resolved=\"False\" />"
 - uid: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.logPii()"
   fullName: "com.microsoft.aad.msal4j.AbstractClientApplicationBase.logPii()"
   name: "logPii()"
@@ -258,4 +265,4 @@ implements:
 - "<xref href=\"com.microsoft.aad.msal4j.IClientApplicationBase?alt=com.microsoft.aad.msal4j.IClientApplicationBase&text=IClientApplicationBase\" data-throw-if-not-resolved=\"False\" />"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AppTokenProviderParameters.yml

@@ -128,4 +128,4 @@ methods:
 type: "class"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AuthenticationErrorCode.yml

@@ -292,4 +292,4 @@ type: "class"
 desc: "Class containing error codes returned by the service or generated by the client"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AuthenticationErrorMessage.yml

@@ -43,4 +43,4 @@ fields:
 type: "class"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.yml

@@ -68,6 +68,16 @@ methods:
   syntax: "public AuthorizationCodeParameters.AuthorizationCodeParametersBuilder extraHttpHeaders(Map<String,String> extraHttpHeaders)"
   returns:
     type: "<xref href=\"com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder?alt=com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder&text=AuthorizationCodeParametersBuilder\" data-throw-if-not-resolved=\"False\" />"
+- uid: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.extraQueryParameters(java.util.Map<java.lang.String,java.lang.String>)"
+  fullName: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.extraQueryParameters(Map<String,String> extraQueryParameters)"
+  name: "extraQueryParameters(Map<String,String> extraQueryParameters)"
+  nameWithType: "AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.extraQueryParameters(Map<String,String> extraQueryParameters)"
+  parameters:
+  - name: "extraQueryParameters"
+    type: "<xref href=\"java.util.Map?alt=java.util.Map&text=Map\" data-throw-if-not-resolved=\"False\" />&lt;<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />,<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />&gt;"
+  syntax: "public AuthorizationCodeParameters.AuthorizationCodeParametersBuilder extraQueryParameters(Map<String,String> extraQueryParameters)"
+  returns:
+    type: "<xref href=\"com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder?alt=com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder&text=AuthorizationCodeParametersBuilder\" data-throw-if-not-resolved=\"False\" />"
 - uid: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.redirectUri(java.net.URI)"
   fullName: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.AuthorizationCodeParametersBuilder.redirectUri(URI redirectUri)"
   name: "redirectUri(URI redirectUri)"
@@ -109,4 +119,4 @@ methods:
 type: "class"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AuthorizationCodeParameters.yml

@@ -77,6 +77,15 @@ methods:
   desc: "Adds additional headers to the token request"
   returns:
     type: "<xref href=\"java.util.Map?alt=java.util.Map&text=Map\" data-throw-if-not-resolved=\"False\" />&lt;<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />,<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />&gt;"
+- uid: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.extraQueryParameters()"
+  fullName: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.extraQueryParameters()"
+  name: "extraQueryParameters()"
+  nameWithType: "AuthorizationCodeParameters.extraQueryParameters()"
+  summary: "Adds additional query parameters to the token request"
+  syntax: "public Map<String,String> extraQueryParameters()"
+  desc: "Adds additional query parameters to the token request"
+  returns:
+    type: "<xref href=\"java.util.Map?alt=java.util.Map&text=Map\" data-throw-if-not-resolved=\"False\" />&lt;<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />,<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />&gt;"
 - uid: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.redirectUri()"
   fullName: "com.microsoft.aad.msal4j.AuthorizationCodeParameters.redirectUri()"
   name: "redirectUri()"
@@ -110,4 +119,4 @@ implements:
 - "<xref href=\"com.microsoft.aad.msal4j.IAcquireTokenParameters?alt=com.microsoft.aad.msal4j.IAcquireTokenParameters&text=IAcquireTokenParameters\" data-throw-if-not-resolved=\"False\" />"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8

java/docs-ref-autogen/com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder.yml

@@ -106,6 +106,18 @@ methods:
   desc: "Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain hint is a registered domain for the tenant."
   returns:
     type: "<xref href=\"com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder?alt=com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder&text=Builder\" data-throw-if-not-resolved=\"False\" />"
+- uid: "com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder.extraQueryParameters(java.util.Map<java.lang.String,java.lang.String>)"
+  fullName: "com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder.extraQueryParameters(Map<String,String> val)"
+  name: "extraQueryParameters(Map<String,String> val)"
+  nameWithType: "AuthorizationRequestUrlParameters.Builder.extraQueryParameters(Map<String,String> val)"
+  summary: "Query parameters that you can add to the request, in addition to the list of parameters already provided."
+  parameters:
+  - name: "val"
+    type: "<xref href=\"java.util.Map?alt=java.util.Map&text=Map\" data-throw-if-not-resolved=\"False\" />&lt;<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />,<xref href=\"java.lang.String?alt=java.lang.String&text=String\" data-throw-if-not-resolved=\"False\" />&gt;"
+  syntax: "public AuthorizationRequestUrlParameters.Builder extraQueryParameters(Map<String,String> val)"
+  desc: "Query parameters that you can add to the request, in addition to the list of parameters already provided."
+  returns:
+    type: "<xref href=\"com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder?alt=com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder&text=Builder\" data-throw-if-not-resolved=\"False\" />"
 - uid: "com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder.extraScopesToConsent(java.util.Set<java.lang.String>)"
   fullName: "com.microsoft.aad.msal4j.AuthorizationRequestUrlParameters.Builder.extraScopesToConsent(Set<String> val)"
   name: "extraScopesToConsent(Set<String> val)"
@@ -217,4 +229,4 @@ methods:
 type: "class"
 metadata: {}
 package: "com.microsoft.aad.msal4j"
-artifact: com.microsoft.azure:msal4j:1.13.3
+artifact: com.microsoft.azure:msal4j:1.13.8